Funding a wallet

An agent can't fund its own wallet. Moving money in is always a person's action, in the console or through your own code on their behalf.

#Ask what's available first

Funding options depend on which payment providers the gateway has connected. Ask instead of guessing:

curl -s https://api.zanora.dev/v1/rail/providers -H "x-api-key: $WKEY"

{
  "sandbox": false,
  "providers": [
    { "id": "stripe", "name": "Stripe", "roles": ["funding"], "currencies": ["USD"],
      "rails": ["card", "ach"], "topUps": true, "depositAddresses": false, "faucet": false, "status": "active" },
    { "id": "circle", "name": "Circle", "roles": ["funding", "payout"], "currencies": ["USDC"],
      "rails": ["usdc_base"], "topUps": false, "depositAddresses": true, "faucet": false, "status": "active" }
  ]
}

#Top-up (card or bank)

The console's Fund button is the easiest route: it takes a card and handles confirmation. From the API:

curl -s -X POST https://api.zanora.dev/v1/wallets/$WAL/topup -H "x-api-key: $WKEY" \
  -H 'content-type: application/json' -d '{"amountMinor":"2000"}'
# → {"intent":{"externalRef":"pi_…","asset":"USD","amountMinor":"2000","status":"requires_payment_method","hostedUrl":"…"}}

Finish the payment where the intent says: hostedUrl if present, or clientSecret for your own card form. The wallet is credited when the card processor confirms, not when this call returns. If the card is declined, status is declined with a declineReason. That's an answer, not an error.

#USDC deposit address

curl -s -X POST https://api.zanora.dev/v1/wallets/$WAL/deposit-address -H "x-api-key: $WKEY" \
  -H 'content-type: application/json' -d '{"asset":"USDC","chain":"base"}'
# → {"address":{"id":"…","walletId":"wal_…","treasuryProviderId":"circle","chain":"base","asset":"USDC","address":"0x5f3a…","createdAt":"…"}}

• Calling it again returns the same address, never a second one.
• Send only USDC on Base to it. Other tokens and chains aren't credited.
• The wallet is credited in USD at 1:1 once the transfer is confirmed.
• If USDC is trading more than 0.5% away from $1 when the deposit arrives, it's held, not credited at a guessed rate. Zanora checks held deposits again automatically, and credits them once the price is back within the band.

GET /v1/wallets/$WAL/deposit-addresses lists a wallet's addresses. The zanora_deposit_addresses MCP tool reports them to an agent, so it can tell its user where to send money.

#Testnet faucet

On a testnet deployment where a provider reports faucet: true:

curl -s -X POST https://api.zanora.dev/v1/wallets/$WAL/faucet -H "x-api-key: $WKEY"

This sends real testnet USDC to the wallet's deposit address, and it's credited the same way as any deposit.

#Development shortcut

Only on a local or sandbox gateway (sandbox: true):

curl -s -X POST http://127.0.0.1:8080/v1/wallets/$WAL/fund -H "x-api-key: $WKEY" \
  -H 'content-type: application/json' -d '{"amountMinor":"5000","rail":"card"}'

It credits instantly against a simulated deposit. Anywhere with a real payment provider connected, including the hosted platform, it returns 501 NOT_SUPPORTED.

#Checking it landed

curl -s https://api.zanora.dev/v1/wallets/$WAL/balance -H "x-api-key: $WKEY"
curl -s https://api.zanora.dev/v1/rail/transactions -H "x-api-key: $WKEY"   # each deposit and its state

A balance of zero right after you fund is normal. Card payments usually confirm within seconds and USDC within minutes.