Quickstart

This guide creates an Ethereum wallet, saves its one-time credential, and resolves the wallet as an isolated runtime.

1. Request an API credential

Contact the Naven team to request Wallet API access. After approval, you will receive a server-side credential beginning with naven_api_.

Store it in an environment variable:

export NAVEN_API_KEY="naven_api_..."

Do not expose this credential in browser code.

2. Create a wallet

Choose an externalId that is stable in your own system. It can represent a user, agent, or automation.

curl https://api.naven.network/v1/wallets \
  --request POST \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "agent_123",
    "name": "Trading Agent",
    "chainType": "ethereum",
    "metadata": {
      "environment": "production"
    }
  }'

A successful first request returns 201 Created:

{
  "code": 0,
  "message": "ok",
  "data": {
    "created": true,
    "wallet": {
      "id": "1d447cc4-5082-4adf-99a7-682ed227d17a",
      "externalId": "agent_123",
      "name": "Trading Agent",
      "provider": "privy",
      "address": "0x1234...",
      "chainType": "ethereum",
      "status": "active",
      "metadata": {
        "environment": "production"
      },
      "lastError": null,
      "createdAt": "2026-07-16T10:00:00.000Z",
      "updatedAt": "2026-07-16T10:00:01.000Z"
    },
    "credential": {
      "id": "fa187bac-9420-4804-af70-87ee3bc53e6b",
      "name": "default",
      "prefix": "naven_wallet_...",
      "status": "active",
      "lastUsedAt": null,
      "expiresAt": null,
      "createdAt": "2026-07-16T10:00:01.000Z",
      "secret": "naven_wallet_..."
    }
  }
}

Save data.wallet.id and data.credential.secret. The full wallet credential is returned only once.

3. Resolve the wallet from a runtime

Give the wallet credential only to the runtime that should use this wallet:

export NAVEN_WALLET_KEY="naven_wallet_..."

curl https://api.naven.network/v1/wallets/me \
  --header "Authorization: Bearer $NAVEN_WALLET_KEY"

The credential resolves directly to one wallet. The runtime does not submit a wallet ID and cannot use the credential to access another wallet.

4. Make an x402 request

Fund the wallet with the token required by the target x402 resource, then call the resource through Naven:

curl https://api.naven.network/v1/wallets/me/pay-and-call \
  --request POST \
  --header "Authorization: Bearer $NAVEN_WALLET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://api.naven.network/x402-test/ping",
    "method": "GET",
    "maxPayment": {
      "network": "eip155:4663",
      "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
      "amount": "100"
    }
  }'

maxPayment.amount is the maximum atomic token amount for this request. The example permits up to 0.0001 USDG with 6 decimals.

Naven calls the resource, validates the returned x402 requirements, signs with the Privy wallet, retries with the payment header, and returns the upstream response.

Read x402 Payments before using this endpoint in production.

5. Retry wallet creation safely

Wallet creation is idempotent for the same externalId. Repeating the create request returns the existing active wallet with:

{
  "created": false,
  "credential": null
}

If the first credential was not saved, create a replacement with POST /v1/wallets/:walletId/credentials.

Next steps

Review Authentication
Learn how x402 Payments are constrained
Explore the complete API Reference