Wallets

Wallets in AgentPay represent the payment identity for a given API key and network. Each API key can have one or more wallets; when your agent pays a 402-protected API, the AgentPay API selects the wallet that matches the payment requirements' network (e.g. Base) and uses it to satisfy the payment via the x402 facilitator.

Creating a wallet

Create a wallet by sending POST /wallets with your API key and the desired network. The response includes a unique wallet_id, the network, and when CDP is configured, an address (on-chain Base address you can fund with USDC). After creating a wallet, fund it with USDC on Base — see Funding your wallet.

POST /wallets
X-Api-Key: pk_...
Content-Type: application/json

{ "network": "base" }

# Response 201 (with CDP: address present; without CDP: address is null)
{
  "id": "uuid",
  "wallet_id": "cdp-wallet-id or agentpay_...",
  "network": "base",
  "address": "0x..."
}

Listing wallets

List all wallets associated with your API key using GET /wallets/me. This is useful for verifying that a wallet exists for a given network before making payments or for displaying balances in a dashboard.

GET /wallets/me
X-Api-Key: pk_...

# Response 200
{
  "wallets": [
    { "id": "uuid", "wallet_id": "...", "network": "base", "address": "0x..." }
  ]
}

Deleting a wallet

Delete a wallet with DELETE /wallets/:id (use the wallet id from the list). Returns 204 on success or 404 if the wallet does not exist or does not belong to your API key.

Networks

Currently Base is the supported network. Payments and USDC settlement occur on Base. The x402 facilitator (e.g. OpenFacilitator) handles verification and on-chain settlement; AgentPay builds the payment payload and forwards it to the facilitator based on your FACILITATOR_URL configuration.

Wallet selection during payment

When you call POST /v1/pay (or when the SDK does so after receiving a 402), the API decodes the payment requirements and reads the network field. It then looks up a wallet for your API key and that network. If no wallet exists, the API returns 400 with a message instructing you to create one via POST /wallets with the appropriate network. Creating a wallet for base before calling paid APIs on Base is required.

Dashboard

The AgentPay dashboard shows wallets for the logged-in user's API key. You can create and list wallets from the UI as well as from the API.