# Wallets

> Create and list wallets, read balances and ledgers, fund them, and freeze or unfreeze them.

### `POST /v1/wallets`

Scope `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 |

### `GET /v1/wallets`

Scope `wallets:read`. Your wallets: `{ wallets }`. A provider key returns its settlement wallet.

### `GET /v1/wallets/:id`

Scope `wallets:read`. Wallet details: owner, status, and whether it's frozen.

### `GET /v1/wallets/:id/balance`

Scope `wallets:read`. `{ balanceMinor, availableMinor, currency }`. Available is the balance minus holds. It's calculated from the ledger every time.

### `GET /v1/wallets/:id/ledger`

Scope `wallets:read`. Every ledger entry for the wallet (amounts as strings). Refunds and corrections appear as new entries. Nothing is removed.

### `POST /v1/wallets/:id/topup`

Scope `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.

### `POST /v1/wallets/:id/deposit-address`

Scope `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 } }`.

### `GET /v1/wallets/:id/deposit-addresses`

Scope `wallets:read`. The wallet's registered deposit addresses.

### `POST /v1/wallets/:id/faucet`

Scope `wallets:write`. **Testnet deployments only.** Sends test USDC to the wallet's deposit address. Body is optional: `{ address? }`.

### `POST /v1/wallets/:id/fund`

Scope `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.

### `POST /v1/wallets/:id/freeze`

Scope `wallets:write`. Blocks all outgoing payments. No body.

### `POST /v1/wallets/:id/unfreeze`

Scope `wallets:write`. Reverses a freeze. No body.

### `POST /v1/wallets/:id/resume-provider`

Scope `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 }`.

### `GET /v1/wallets/:id/breaker/:providerId`

Scope `wallets:read`. Whether a seller is paused for this wallet: `{ walletId, providerId, paused }`.