Nava Integrator API reference
Developer Preview
The HTTP API behind Partner integration. Your backend uses it to read a user's policy and verify transactions before they run. The TypeScript SDK wraps every call. See the interactive reference for full schemas.
Authentication
Send both headers on every request, from your server only:
x-app-id: <NAVA_APP_ID>
x-api-key: <NAVA_INTEGRATION_KEY>Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /integrator/policies?walletAddress= | Read the wallet's current policy. |
POST | /integrator/verifications | Verify a proposed transaction. |
GET | /integrator/verifications/{id} | Read a verification and its verdict. |
POST | /integrator/verifications/{id}/execution | Report that an approved transaction executed. |
POST | /integrator/verifications/{id}/cancel | Release a verification you will not execute. |
{id} is the verification id or its requestHash.
Cancelling releases the reserved spend for EVM transactions. A Hyperliquid order's spend hold clears only when Hyperliquid reports the order filled or finished.
Verdicts
The verification response usually includes the verdict. Read verdict.outcome, not status: status can stay PENDING after Nava decides.
verdict.outcome | canExecute | Do this |
|---|---|---|
approved | true | Execute, then report execution. |
rejected | false | Do not execute. verdict.humanReason explains why. |
pending, or verdict is null | false | Poll GET /integrator/verifications/{id}. |
Retries
Idempotency-Key is optional, but you need it to retry safely. Without it, a retry after a timeout creates a second verification that reserves spend again.
- Create one key per action, such as one trade, and store it before you send the request.
- Retry with the same key and the exact same body. Nava returns the original verification.
- Do not rebuild the body for a retry. A different body with the same key returns
409 idempotency_conflict. - Keys are 1 to 128 visible ASCII characters, with no spaces. Any other key returns
400.
Errors
| Status | Meaning |
|---|---|
400 | Invalid body or Idempotency-Key, or txHash missing from an on-chain execution report. |
401 | Missing or invalid x-app-id or x-api-key. |
403 | The wallet is not registered for the transaction's chain. |
404 | The wallet or verification is not in this integration. |
409 | The verification is not approved, was cancelled, or was already executed (with a different txHash, when reporting). Also returned when an Idempotency-Key is reused with a different body. |
429 | Rate limited: 60 requests a minute, 120 for policy reads. |