API Reference

Wallet provisioning, x402 payment, spot trading, lookup, and credential endpoints.

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.

Arcus spot operations

See Arcus Spot Trading for token discovery, balances, quotes, approvals, execution, and operation status. All spot routes use the wallet-scoped credential.

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

ERC-8004 identity

See ERC-8004 identity for optional managed or external ownership, registration, receipt reconciliation and public metadata.

On this page