API Reference

Base URL

https://api.naven.network

All responses use the same envelope:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Error responses use a non-zero code and may include validation details in data.

Wallet object

Field	Type	Description
`id`	string	Naven wallet ID
`externalId`	string	Stable identifier supplied by your application
`name`	string	Display name
`provider`	string	Wallet provider; currently `privy`
`address`	string or null	On-chain address
`chainType`	string	`ethereum`
`status`	string	`provisioning`, `active`, or `failed`
`metadata`	object or null	Caller-defined scalar metadata
`lastError`	string or null	Most recent provisioning failure
`createdAt`	ISO 8601 string	Creation time
`updatedAt`	ISO 8601 string	Last update time

List wallets

GET /v1/wallets
Authorization: Bearer naven_api_...

Returns wallet objects ordered from newest to oldest.

Create a wallet

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

Request body:

Field	Required	Description
`externalId`	yes	Stable caller-defined ID, 1–200 characters
`name`	yes	Display name, 1–200 characters
`chainType`	no	`ethereum`; defaults to `ethereum`
`metadata`	no	String-keyed object with string, number, or boolean values

The first successful request returns 201 Created, the wallet, and a one-time default wallet credential. Reusing an active wallet's externalId returns 200 OK, created: false, and no credential.

An externalId cannot be reused with a different chainType.

Get a wallet

GET /v1/wallets/:walletId
Authorization: Bearer naven_api_...

Returns 404 Not Found when the wallet does not exist or does not belong to your API credential.

List wallet credentials

GET /v1/wallets/:walletId/credentials
Authorization: Bearer naven_api_...

Returns credential metadata. Full secrets are never included.

Create a wallet credential

POST /v1/wallets/:walletId/credentials
Authorization: Bearer naven_api_...
Content-Type: application/json

Request body:

Field	Required	Description
`name`	yes	Credential name, 1–100 characters
`expiresAt`	no	ISO 8601 expiration timestamp

Returns 201 Created. The response includes the full secret exactly once. The wallet must be active.

Revoke a wallet credential

DELETE /v1/wallets/:walletId/credentials/:credentialId
Authorization: Bearer naven_api_...

Marks the credential as revoked and returns its updated metadata.

Resolve the current wallet

GET /v1/wallets/me
Authorization: Bearer naven_wallet_...

Returns the wallet and metadata for the wallet credential used in the request. This endpoint does not accept the management API credential.

Pay and call an x402 resource

POST /v1/wallets/me/pay-and-call
Authorization: Bearer naven_wallet_...
Content-Type: application/json

Request body:

Field	Required	Description
`url`	yes	Public HTTPS x402 resource URL
`method`	no	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`; defaults to `GET`
`headers`	no	Up to 50 headers forwarded to the upstream resource
`body`	no	String or JSON body; not allowed with `GET`
`maxPayment.network`	yes	Expected EVM CAIP-2 network such as `eip155:8453`
`maxPayment.asset`	yes	Expected ERC-20 token contract address
`maxPayment.amount`	yes	Maximum payment in atomic token units

The endpoint supports x402 version 2 and the exact EVM scheme. It makes an initial upstream request and pays only when all returned payment requirements match maxPayment.

The response contains:

{
  "code": 0,
  "message": "ok",
  "data": {
    "upstream": {
      "status": 200,
      "headers": {
        "content-type": "application/json"
      },
      "body": {}
    },
    "payment": {
      "id": "4c317dea-a052-4e83-9760-e3ac1cb35350",
      "status": "settled",
      "x402Version": 2,
      "network": "eip155:4663",
      "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
      "amount": "100",
      "payTo": "0x...",
      "transaction": "0x...",
      "settlement": {}
    }
  }
}

payment is null when the upstream resource does not require payment. Binary response bodies are returned as base64.

Status codes

Status	Meaning
`200`	Read succeeded, idempotent wallet already existed, or credential was revoked
`201`	Wallet or credential was created
`400`	Request body or x402 payment requirements failed validation
`401`	Credential is missing, invalid, expired, or revoked
`413`	Forwarded request body exceeded the configured limit
`404`	Wallet or credential was not found within the caller's access boundary
`409`	Resource state conflicts with the request
`502`	Wallet provisioning, x402 signing, or the upstream request failed
`504`	The upstream request timed out

On this page