Endpoints
Wallets
Create and list wallets, read balances and ledgers, fund them, and freeze or unfreeze them.
/v1/walletsScope wallets:write. Creates a wallet in your workspace (workspaceId comes from your key).
| Field | Type | Required | Notes |
|---|---|---|---|
ownerType | "agent" | "workspace" | yes | agent for anything that buys |
ownerId | string | yes | your label for the agent, e.g. invoice-bot |
publicKeyPem | string | agents: yes | the ed25519 public key that payment proofs are checked against |
/v1/walletsScope wallets:read. Your wallets: { wallets }. A provider key returns its settlement wallet.
/v1/wallets/:idScope wallets:read. Wallet details: owner, status, and whether it's frozen.
/v1/wallets/:id/balanceScope wallets:read. { balanceMinor, availableMinor, currency }. Available is the balance minus holds. It's calculated from the ledger every time.
/v1/wallets/:id/ledgerScope wallets:read. Every ledger entry for the wallet (amounts as strings). Refunds and corrections appear as new entries. Nothing is removed.
/v1/wallets/:id/topupScope wallets:write. Starts a card or bank payment into the wallet. Body { amountMinor, asset?, treasuryProviderId? }. Returns { intent: { externalRef, status, amountMinor, hostedUrl?, clientSecret?, declineReason? } }. The wallet is credited when the payment processor confirms. Returns 501 NOT_SUPPORTED if no connected provider takes top-ups.
/v1/wallets/:id/deposit-addressScope wallets:write. Gets or creates the wallet's USDC deposit address. Body is optional: { asset?: "USDC", chain?: "base", treasuryProviderId? }. It's idempotent: asking twice returns the same address. Returns { address: { address, chain, asset, walletId, treasuryProviderId, createdAt } }.
/v1/wallets/:id/deposit-addressesScope wallets:read. The wallet's registered deposit addresses.
/v1/wallets/:id/faucetScope wallets:write. Testnet deployments only. Sends test USDC to the wallet's deposit address. Body is optional: { address? }.
/v1/wallets/:id/fundScope wallets:write. Local and sandbox gateways only. Credits the wallet instantly against a simulated deposit. Body { amountMinor, rail? }. Returns 501 NOT_SUPPORTED anywhere a real payment provider is connected.
/v1/wallets/:id/freezeScope wallets:write. Blocks all outgoing payments. No body.
/v1/wallets/:id/unfreezeScope wallets:write. Reverses a freeze. No body.
/v1/wallets/:id/resume-providerScope wallets:write. Lifts the pause on a seller that failed three calls in a row for this wallet (5xx, thrown handler, MCP isError or timeout; 4xx responses don't count). Body { providerId }. Returns { ok, paused }.
/v1/wallets/:id/breaker/:providerIdScope wallets:read. Whether a seller is paused for this wallet: { walletId, providerId, paused }.