API Reference

Base URL and interactive reference

https://api.naven.network

• Interactive OpenAPI explorer
• Raw OpenAPI JSON

Project management responses use Naven's { code, message, data } envelope. Payment Intent endpoints return the Payment Intent or x402 object directly.

Credentials

Privy identity token

Used only by the signed-in Naven Workspace:

Authorization: Bearer <privy-identity-token>

Project API key

Used only by your backend:

Authorization: Bearer naven_api_...

Project management

The complete API key secret is returned exactly once. Later Project responses include only its prefix and metadata.

Create Payment Intent

POST /v1/payment-intents
Authorization: Bearer naven_api_...
Content-Type: application/json

The request cannot override payTo, asset, network, facilitator, token metadata, or payment timeout.

Idempotency

(merchantId, externalId) is unique. Retrying the same request returns the existing intent with 200 OK. Reusing the same external ID with different amount, customer reference, description, or metadata returns 409 Conflict.

Get Payment Intent

GET /v1/payment-intents/:intentId
Authorization: Bearer naven_api_...

Returns 404 when the intent does not exist or belongs to another Project. This endpoint is the authoritative source for business fulfillment. failureCode and failureMessage are nullable and describe the latest definitive failure or reconciliation condition.

Reconcile Payment Intent

POST /v1/payment-intents/:intentId/reconcile
Authorization: Bearer naven_api_...

Idempotently checks a settling Robinhood USDG authorization against Naven's indexed facilitator transactions. It returns the current Payment Intent and may move it to settled, or return an expired unused authorization to pending while the Payment Intent itself remains valid. Normal recovery is automatic; this endpoint is available for manual operational recovery.

Pay Payment Intent

POST /v1/payment-intents/:intentId/pay

This endpoint is public and must not receive the Project API key.

Initial response:

402 Payment Required
PAYMENT-REQUIRED: <encoded-x402-v2-requirement>
Cache-Control: no-store

Paid retry:

POST /v1/payment-intents/:intentId/pay
PAYMENT-SIGNATURE: <encoded-x402-v2-payment>

Successful response:

200 OK
PAYMENT-RESPONSE: <encoded-settlement-response>
Cache-Control: no-store

{
  "id": "pi_01JABC",
  "status": "settled",
  "amountUsdCents": 9900,
  "currency": "USD",
  "settlement": {
    "transaction": "0x...",
    "network": "eip155:4663",
    "payer": "0x...",
    "settledAt": "2026-07-21T13:16:12.000Z"
  }
}

Statuses

Error codes