The @cai.com wallet API: balances, transfers, and the hosted-action flow

The wallet is the most-requested deep-dive from the four-pillars post. This post walks through the wallet API in detail: how to check balances, how to send a payment, how the user-confirmation pattern works, and the difference between custodial and self-custody.

The wallet in one sentence

A custodial multi-chain stablecoin wallet. Six chains. External wallets supported. MoonPay for fiat on-ramp. One custodial account for pay, transfer, convert, and bridge. No private key in chat.

Checking balances

The POST /get-wallet-balances endpoint returns the user's balances on one or more chains. The request is a JSON body with the chains and tokens to query.

curl -X POST https://api.cai.com/functions/v1/get-wallet-balances \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "chains": ["ETH", "polygon", "base"],
    "tokens": ["USDC", "USDT"]
  }'

The response includes the custodial wallet_binding addresses and any linked subwallets (read-only RPC for the external wallets the user has connected). Entries may include linked_subwallet: true for external wallet balances.

Common gotcha. If you query a chain the user hasn't deposited to yet, the response may include empty activity for that chain. That is expected behavior; the chain is supported, the indexer just hasn't seen any activity for this user yet.

Sending a payment

The POST /wallet-custodial-transfer endpoint initiates a payment. The response is a hosted-action URL. The user opens it, sees the recipient, the amount, and the chain, and taps once.

curl -X POST https://api.cai.com/functions/v1/wallet-custodial-transfer \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "0x...",
    "amount": "10.00",
    "chain": "base",
    "token": "USDC"
  }'

The response:

{
  "transfer_id": "tx_...",
  "hosted_action_url": "https://cai.com/act/...",
  "expires_at": "2026-07-04T12:34:56Z"
}

The hosted-action URL is the user-confirmation pattern. The agent's API key is the authorization to call the CAI API on the user's behalf, but every transfer still needs the user's consent on the hosted-action page. The page is HTTPS, the tap is bound to a single transaction, and the URL expires in a short window. If the user does nothing, the payment does not go through.

Polling for the receipt

After the user taps once, the agent polls POST /transfer-status for the receipt.

curl -X POST https://api.cai.com/functions/v1/transfer-status \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "0x..."}'

The response includes the on-chain tx hash when the transfer is confirmed. The agent can then show the receipt to the user.

Custodial vs self-custody

A custodial wallet means the user does not hold the private key. CAI holds it. The user gets a @cai.com address on each of six chains and can pay, transfer, convert, and bridge from any of them.

The difference from self-custody is the user-confirmation pattern. With self-custody, the user holds the key, signs each transaction, and is responsible for key management. With CAI's custodial wallet, the user holds the address and the user-confirmation tap; CAI holds the key and the signing infrastructure. The trade-off: CAI is a trusted third party for custody, but the user never has to paste a private key into an agent conversation.

External wallets are supported. Connect a MetaMask or a Ledger and the user keeps custody of their external assets while using CAI for the day-to-day. The external wallets appear as linked subwallets in the get-wallet-balances response.

Guardrails. The wallet has a $200/day auto-limit while CAI completes its security audit. New recipients and new devices always require confirmation. Think of it like cash in your pocket, perfect for daily spending. The vault product (multi-sig, time-locks) is coming for larger balances.

Top-up flows

To add funds to the wallet, the user can:

• Send from an external wallet to the CAI custodial address on the chosen chain. The address is in the account dashboard.
• Buy with MoonPay (fiat on-ramp). The account dashboard has a "Buy with MoonPay" button for each chain. MoonPay is a third-party service; regional availability and KYC requirements apply.
• Use WeChat Pay (Planned). The WeChat Pay path is documented in cai.com/capabilities.html.

Each top-up flow eventually surfaces a hosted-action URL or a direct deposit link that the user completes on the chosen rail.

The wallet API is in cai.com/skill.md. The hosted-action flow is in cai.com/agent-payment.html. Apply at cai.com/app to get a wallet.

---

If you wired the wallet API and got an unexpected balance, a 5xx, or a missing wallet_binding

Comment below with:

1. What you ran -- the install command, the request, the MCP host config. Copy the actual command or request.
2. What you expected -- one sentence.
3. What you got -- the error message, the empty response, the unexpected behavior. Paste it verbatim.
4. Your environment -- OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/app to sign up.