Nava Guardian API reference

This page documents the lower-level Nava Service transport used to submit a structured proposed action and read its policy verdict. Most integrations should use the Nava MCP server or TypeScript SDK instead.

Authentication

Send one agent API key header on both operations:

x-api-key: <agent-api-key>

Do not also send a bearer token. For least privilege, use an agent key with verdicts:create:own. The status route requires authentication and confirms that the caller owns the transaction.

Never send the key in a URL, persist it in request metadata, or log it.

POST /transactions

Submit a canonical action for policy evaluation. Agent keys default to policy routing, but clients should send arbiter: "policy" explicitly.

Request body

{
  "escrowAddress": "0x1111111111111111111111111111111111111111",
  "prompt": "Swap WETH for USDC on Uniswap on Sepolia.",
  "proposedTx": {
    "protocol": "uniswap",
    "chainId": 11155111,
    "to": "0x2222222222222222222222222222222222222222",
    "data": "0x",
    "value": "0x0"
  },
  "metadata": {
    "environment": "test"
  },
  "arbiter": "policy"
}

The addresses and action data are placeholders. Replace them before use. Agent keys cannot use the pre-encrypted request shape.

201 response

The response is the created transaction record. The integration-critical field is requestHash:

{
  "id": "11111111-2222-3333-4444-555555555555",
  "requestHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "description": "Swap WETH for USDC on Uniswap on Sepolia.",
  "status": "PENDING"
}

Reject a successful HTTP response that lacks a non-empty string requestHash.

GET /transactions/:requestHash/approval-status

Read the request's approval envelope and Nava Guardian verdict.

Path parameter

Response envelope

Verdict object

Check results

Each checks[] item contains a checkId, status, optional failure code, human-readable reason, optional triggering policy field, and an optional non-negative legIndex for a decoded multi-leg action. The table below is the complete published preview check contract. See Policy checks for human-readable behavior and applicability.

Other enum values

An approved verdict must use reasonCode: "allowed"; a pending verdict must use reasonCode: "pending"; and a rejected verdict must use a violation code. Except for cross-cutting decode_failure and data_unavailable, a rejected reason code must match a failed check. asset_identity_unresolved is also cross-cutting and can be returned with no failed check. A data-dependent check can use data_unavailable in place of its policy-violation code.

See Failure modes and recovery for the definition and builder response for every reason code, degraded-state examples, and API-key incident handling.

Approved response

{
  "verdict": {
    "schemaVersion": 1,
    "outcome": "approved",
    "reasonCode": "allowed",
    "humanReason": "The action satisfies the configured policy.",
    "triggeringPolicyField": null,
    "checks": [
      {
        "checkId": "venue",
        "status": "passed",
        "code": null,
        "humanReason": "The venue is configured.",
        "triggeringPolicyField": null
      }
    ],
    "evidence": {
      "decodedAction": {
        "protocol": "uniswap",
        "chainId": 11155111
      },
      "observations": {},
      "sources": []
    },
    "policyVersion": 3,
    "latencyMs": 42,
    "dataFreshness": {
      "overall": "fresh",
      "sources": []
    },
    "trust": {
      "level": "high",
      "notes": null
    },
    "redaction": {
      "redacted": false,
      "fields": []
    },
    "usdNotional": null,
    "timestamp": "2026-07-20T12:00:00.000Z"
  }
}

Rejected response

{
  "verdict": {
    "schemaVersion": 1,
    "outcome": "rejected",
    "reasonCode": "chain_not_allowed",
    "humanReason": "The proposed chain is not allowed by the active policy.",
    "triggeringPolicyField": "venues.uniswap.chainAllowlist",
    "checks": [
      {
        "checkId": "chain",
        "status": "failed",
        "code": "chain_not_allowed",
        "humanReason": "Chain 11155111 is not in the allowlist.",
        "triggeringPolicyField": "venues.uniswap.chainAllowlist"
      }
    ],
    "evidence": {
      "decodedAction": {
        "protocol": "uniswap",
        "chainId": 11155111
      },
      "observations": {
        "chainId": 11155111
      },
      "sources": []
    },
    "policyVersion": 3,
    "latencyMs": 37,
    "dataFreshness": {
      "overall": "fresh",
      "sources": []
    },
    "trust": {
      "level": "high",
      "notes": null
    },
    "redaction": {
      "redacted": false,
      "fields": []
    },
    "usdNotional": null,
    "timestamp": "2026-07-20T12:00:00.000Z"
  }
}

Status-code handling

Polling, retries, and idempotency

Use bounded exponential backoff for a missing, null, or pending verdict and for transient status-read failures. Cap both the delay and total attempts, pass an abort signal to every request and delay, and fail closed when the bound is reached.

The Developer Preview submit DTO and controller expose no idempotency key. Do not automatically retry POST /transactions: a repeat can create another request. GET /transactions/:requestHash/approval-status is read-only and can be retried within the polling bound after 429, transient 5xx, or network interruption.

Malformed JSON, an unknown outcome, inconsistent required verdict fields, or a persistently unavailable service is not approval. Stop the action and surface a non-sensitive error alongside the requestHash when available.