Wallet API

Manage wallets for on-chain transactions and payments

Wallet API

Manage wallets for on-chain transactions and payments. Supports both session-based wallets and Coinbase Developer Platform (CDP) wallets.

Get wallet

GET /api/wallet

Returns 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 [e-mail]"
}

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 (set CDP_PROJECT_ID in environment)

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"
}