Wallet API

Manage wallets for on-chain transactions and payments. Supports session-based wallets, Coinbase Developer Platform (CDP) wallets, and Tempo network balance queries.

Get wallet

GET /api/wallet

Returns wallet information. Behavior depends on whether an address query parameter is provided and on your server configuration.

Tempo balance query

When the address query parameter is present, the endpoint queries the Tempo blockchain for the wallet’s balance and fee token information.

GET /api/wallet?address=0xd8fd...db56f

Query parameters

Parameter	Type	Required	Description
`address`	string	Yes	Hex-encoded wallet address (0x-prefixed)

Response

{
  "address": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
  "chain": "Tempo",
  "chainId": 4217,
  "testnet": false,
  "feeToken": {
    "address": "0x20c0000000000000000000000000000000000000",
    "balance": "12.470000",
    "balanceRaw": "12470000"
  },
  "pathUsd": {
    "address": "0x20c0000000000000000000000000000000000000",
    "balance": "12.470000",
    "balanceRaw": "12470000"
  }
}

Response fields

Field	Type	Description
`address`	string	The queried wallet address
`chain`	string	Network name (`Tempo` or `Tempo Testnet`)
`chainId`	number	Chain ID (`4217` for mainnet, `42431` for testnet)
`testnet`	boolean	Whether the server is configured for testnet
`feeToken.address`	string	Contract address of the user’s configured fee token
`feeToken.balance`	string	Fee token balance formatted with 6 decimals
`feeToken.balanceRaw`	string	Fee token balance in raw units
`pathUsd.address`	string	pathUSD contract address
`pathUsd.balance`	string	pathUSD balance formatted with 6 decimals
`pathUsd.balanceRaw`	string	pathUSD balance in raw units

Balance values are formatted to 6 decimal places. pathUSD uses 6 decimals, not 18. The network is determined server-side by the TEMPO_TESTNET environment variable.

Errors

Code	Description
400	Missing `address` parameter
500	Failed to fetch wallet data from Tempo RPC

CDP / session wallet query

When no address parameter is provided, the endpoint returns CDP or session-based wallet information. When CDP is configured, returns CDP status without authentication. Otherwise, requires session authentication.

Response (CDP configured)

{
  "agenticWallet": {
    "status": "configured",
    "projectId": "abc12345...",
    "features": [
      "create_wallet",
      "get_balance",
      "send_usdc",
      "trade_tokens",
      "x402_payments"
    ]
  },
  "instructions": "CDP Agentic Wallet is configured. Use /api/wallet/cdp/* endpoints."
}

Response (user wallet exists)

{
  "address": "0x...",
  "balance": "0",
  "network": "base-sepolia",
  "hasWallet": true,
  "createdAt": "2026-03-01T00:00:00Z"
}

Response (no wallet)

{
  "address": null,
  "balance": "0",
  "network": "base-sepolia",
  "hasWallet": false,
  "message": "No wallet found. Create one to get started."
}

Errors

Code	Description
401	Unauthorized (no session and CDP not configured)

Wallet actions

POST /api/wallet

Requires session authentication.

Request body

Field	Type	Required	Description
`action`	string	Yes	One of: `create`, `get_seed`, `export_seed`

Action: `create`

Creates a new wallet for the authenticated user.

{
  "address": "0x...",
  "network": "base-sepolia",
  "message": "Wallet created successfully"
}

Returns 400 if a wallet already exists.

Action: `get_seed`

Returns wallet metadata. Private keys are stored encrypted server-side and are never exposed.

{
  "address": "0x...",
  "network": "base-sepolia",
  "createdAt": "2026-03-01T00:00:00Z",
  "warning": "Private keys are stored encrypted server-side and never exposed."
}

Action: `export_seed`

Seed export is disabled for security. Returns 403.

{
  "error": "Seed export is disabled for security. Contact support if you need your private key."
}

Errors

Code	Description
400	Invalid action or wallet already exists
401	Unauthorized
404	No wallet found (for `get_seed`)

Get CDP wallet address

GET /api/wallet/address

Returns the address of the CDP Agentic Wallet.

Response (authenticated)

{
  "authenticated": true,
  "address": "0x..."
}

Response (not authenticated)

When the CDP wallet address cannot be retrieved, the response includes authenticated: false and needsAuth: true. The remaining fields vary by failure reason:

{
  "authenticated": false,
  "needsAuth": true,
  "message": "Run: npx awal auth login your@email.com"
}

If the failure is caused by a configuration error, the response includes error and setup fields instead of message:

{
  "authenticated": false,
  "needsAuth": true,
  "error": "Error description",
  "setup": "Install: npx skills add coinbase/agentic-wallet-skills"
}

Create CDP wallet

POST /api/wallet/create

Creates a new wallet using the Coinbase Developer Platform SDK.

Request body

Field	Type	Required	Description
`email`	string	Yes	Email address for wallet registration

Response

{
  "success": true,
  "walletAddress": "0x...",
  "walletId": "wallet_789",
  "networks": ["base-sepolia", "base"]
}

Errors

Code	Description
400	Email required
500	CDP not configured. Response includes a `setup` field with configuration instructions. Generic errors include a `details` field with the error message.

CDP wallet status

GET /api/wallet/cdp

Returns supported chain information for the CDP wallet.

{
  "status": "ok",
  "type": "evm_wallet",
  "supportedChains": ["base", "base-sepolia"]
}

Create CDP wallet client

POST /api/wallet/cdp

Creates a viem wallet client on Base Sepolia.

Request body

Field	Type	Required	Description
`privateKey`	string	No	Private key (0x-prefixed). A new key is generated if omitted.

Response

{
  "success": true,
  "address": "0x...",
  "network": "base-sepolia"
}

USDC transfer validation

When transferring USDC through the wallet service, the following validation rules apply:

The transfer amount must be a positive finite number. Values such as NaN, Infinity, negative numbers, and zero are rejected.
Amounts are rounded to 6 decimal places (USDC precision). If the rounded value equals zero, the transfer is rejected.

These checks run before any on-chain transaction is initiated.

When payments are initiated through the x402 pay action, additional protections apply: a per-payment maximum of $100, recipient address format validation (EVM or Solana), and audit logging of every payment attempt. See the x402 gateway reference for details.

Wallet top-up

Fund your wallet via Stripe checkout to credit your payment session balance.

Create checkout session

GET /api/wallet/top-up?amount=1000

Creates a Stripe checkout session for wallet top-up. Requires session authentication.

Query parameters

Parameter	Type	Required	Default	Description
`amount`	number	No	`1000`	Amount in cents. Valid values: `500` ( $5), `1000` ($ 10), `2500` ( $25), `5000` ($ 50).

Response

{
  "url": "https://checkout.stripe.com/...",
  "sessionId": "cs_live_..."
}

Field	Type	Description
`url`	string	Stripe checkout URL. Redirect the user here to complete payment.
`sessionId`	string	Stripe checkout session ID

Errors

Code	Description
400	Invalid amount. Must be one of: 500, 1000, 2500, 5000 (cents).
401	Unauthorized — session authentication required
500	Stripe not configured or failed to create checkout session

Stripe webhook

POST /api/wallet/top-up

Handles the Stripe checkout.session.completed webhook to credit the user’s wallet after payment. This endpoint verifies the Stripe webhook signature before processing.

This endpoint is called by Stripe, not by your application. Configure your Stripe webhook to point to this URL with the checkout.session.completed event.

Errors

Code	Description
400	Invalid Stripe webhook signature
500	Stripe not configured or webhook processing failed

MPP payment sessions

Payment sessions enable off-chain, per-call billing for agent requests. Instead of settling every call on-chain, you deposit funds into a session and sign lightweight vouchers that are batched and settled periodically. When you send a request to the gateway with X-Session-Id and X-Wallet-Address headers, the gateway auto-debits your session balance and returns the updated balance in the X-Session-Remaining response header. See MPP payments — sessions for the full protocol description.

List sessions

GET /api/wallet/sessions?address=0x...

Returns all sessions (active and closed) for the given wallet address.

Query parameters

Parameter	Type	Required	Description
`address`	string	Yes	Hex-encoded wallet address (0x-prefixed)

Response

{
  "sessions": [
    {
      "id": "ses_a1b2c3d4e5f6...",
      "userAddress": "0x...",
      "deposit": "10.00",
      "spent": "1.25",
      "remaining": "8.75",
      "vouchers": [],
      "status": "active",
      "createdAt": 1742472000000,
      "lastSettledAt": 1742472000000
    }
  ]
}

Get session

GET /api/wallet/sessions?sessionId=ses_...

Returns a single session by ID.

Query parameters

Parameter	Type	Required	Description
`sessionId`	string	Yes	Session ID (prefixed with `ses_`)

Response

{
  "session": {
    "id": "ses_a1b2c3d4e5f6...",
    "userAddress": "0x...",
    "deposit": "10.00",
    "spent": "1.25",
    "remaining": "8.75",
    "vouchers": [],
    "status": "active",
    "createdAt": 1742472000000,
    "lastSettledAt": 1742472000000
  }
}

Errors

Code	Description
400	Missing `address` or `sessionId` parameter
404	Session not found

Session fields

Field	Type	Description
`id`	string	Unique session ID (`ses_` prefix)
`userAddress`	string	Wallet address that owns the session
`deposit`	string	Total deposited amount in USD
`spent`	string	Total spent via vouchers in USD
`remaining`	string	Remaining balance in USD
`vouchers`	array	Pending vouchers not yet settled on-chain
`status`	string	One of `active`, `settling`, or `closed`
`createdAt`	number	Unix timestamp (ms) when the session was created
`lastSettledAt`	number	Unix timestamp (ms) of the last on-chain settlement

Create session

POST /api/wallet/sessions

Opens a new payment session. If the wallet already has an active session, the existing session is returned instead.

Request body

Field	Type	Required	Description
`address`	string	Yes	Hex-encoded wallet address (0x-prefixed)
`deposit`	string	Yes	Deposit amount in USD (minimum `1.00`, maximum `100.00`)

Response (201 Created)

{
  "session": {
    "id": "ses_a1b2c3d4e5f6...",
    "userAddress": "0x...",
    "deposit": "10.00",
    "spent": "0.00",
    "remaining": "10.00",
    "vouchers": [],
    "status": "active",
    "createdAt": 1742472000000,
    "lastSettledAt": 1742472000000
  }
}

Response (existing session)

{
  "session": { ... },
  "note": "Active session already exists"
}

Errors

Code	Description
400	Missing `address` or `deposit`, deposit below minimum, or deposit above maximum

Close session

DELETE /api/wallet/sessions?sessionId=ses_...

Closes an active session. Any pending vouchers are settled on-chain first, and the remaining balance is returned to the user.

Query parameters

Parameter	Type	Required	Description
`sessionId`	string	Yes	Session ID to close

Response

{
  "success": true,
  "returned": "8.75"
}

Field	Type	Description
`success`	boolean	Whether the session was closed
`returned`	string	Amount in USD returned to the user

Errors

Code	Description
400	Missing `sessionId`, or session could not be closed

Submit voucher

POST /api/wallet/sessions/voucher

Submits a signed voucher to debit the session balance off-chain. This is the primary billing mechanism during an active session — each agent call produces one voucher.

Request body

Field	Type	Required	Description
`sessionId`	string	Yes	Active session ID
`userAddress`	string	Yes	Wallet address that owns the session (0x-prefixed)
`plugin`	string	Yes	Plugin identifier (e.g., `agent`, `generate-text`, `tts`, `stt`)
`signature`	string	Yes	User’s hex-encoded signature (0x-prefixed)
`nonce`	string	Yes	Unique nonce for this voucher

The voucher amount is determined automatically from the plugin’s pricing. See plugin pricing for current rates.

Response

{
  "success": true,
  "session": {
    "id": "ses_a1b2c3d4e5f6...",
    "spent": "0.05",
    "remaining": "9.95",
    "pendingVouchers": 1
  },
  "voucher": {
    "amount": "0.05",
    "plugin": "agent",
    "description": "Agent orchestrator request"
  }
}

Response fields

Field	Type	Description
`session.id`	string	Session ID
`session.spent`	string	Updated total spent in USD
`session.remaining`	string	Updated remaining balance in USD
`session.pendingVouchers`	number	Number of vouchers pending on-chain settlement
`voucher.amount`	string	Amount debited for this call in USD
`voucher.plugin`	string	Plugin that was called
`voucher.description`	string	Human-readable description of the charge

Errors

Code	Description
400	Missing required fields, unknown plugin, session not found, session not active, address mismatch, or insufficient balance
500	Internal error processing the voucher

​Wallet API

​Get wallet

​Tempo balance query

​Query parameters

​Response

​Response fields

​Errors

​CDP / session wallet query

​Response (CDP configured)

​Response (user wallet exists)

​Response (no wallet)

​Errors

​Wallet actions

​Request body

​Action: create

​Action: get_seed

​Action: export_seed

​Errors

​Get CDP wallet address

​Response (authenticated)

​Response (not authenticated)

​Create CDP wallet

​Request body

​Response

​Errors

​CDP wallet status

​Create CDP wallet client

​Request body

​Response

​USDC transfer validation

​Wallet top-up

​Create checkout session

​Query parameters

​Response

​Errors

​Stripe webhook

​Errors

​MPP payment sessions

​List sessions

​Query parameters

​Response

​Get session

​Query parameters

​Response

​Errors

​Session fields

​Create session

​Request body

​Response (201 Created)

​Response (existing session)

​Errors

​Close session

​Query parameters

​Response

​Errors

​Submit voucher

​Request body

​Response

​Response fields

​Errors

Wallet API

Get wallet

Tempo balance query

Query parameters

Response

Response fields

Errors

CDP / session wallet query

Response (CDP configured)

Response (user wallet exists)

Response (no wallet)

Errors

Wallet actions

Request body

Action: `create`

Action: `get_seed`

Action: `export_seed`

Errors

Get CDP wallet address

Response (authenticated)

Response (not authenticated)

Create CDP wallet

Request body

Response

Errors

CDP wallet status

Create CDP wallet client

Request body

Response

USDC transfer validation

Wallet top-up

Create checkout session

Query parameters

Response

Errors

Stripe webhook

Errors

MPP payment sessions

List sessions

Query parameters

Response

Get session

Query parameters

Response

Errors

Session fields

Create session

Request body

Response (201 Created)

Response (existing session)

Errors

Close session

Query parameters

Response

Errors

Submit voucher

Request body

Response

Response fields

Errors