---
title: codespar_wallet
description: The agent's governed funds. Read the balance and Pix key, read the wallet ledger, or mint a Pix copia-e-cola to top the wallet up. Buy-side companion to codespar_pay.
---
import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
This is the wallet the agent spends FROM. Fund it with `receive`, then spend with [`codespar_pay`](/docs/concepts/meta-tools/pay). It is distinct from [`codespar_ledger`](/docs/concepts/meta-tools/ledger), the double-entry books.
## Actions
## Example
`action: "balance"`, the default: the spendable funds and the Pix key bound to the wallet.
```json title="arguments"
{
"name": "codespar_wallet",
"arguments": {
"action": "balance",
"consumer_id": "consumer_0000"
}
}
```
```ts
const result = await session.execute("codespar_wallet", {
action: "balance",
consumer_id: "consumer_0000"
});
```
```python
result = session.execute("codespar_wallet", {
"action": "balance",
"consumer_id": "consumer_0000"
})
```
```bash
codespar tool codespar_wallet \
-i '{
"action": "balance",
"consumer_id": "consumer_0000"
}'
```
```json title="result"
{
"wallet_id": "wlt_0000000000000000",
"balances": [
{
"currency": "BRL",
"balance_minor": 1000,
"available_minor": 1000,
"updated_at": "2026-09-10T12:00:00.000Z"
}
],
"funding_sources": [
{
"funding_source_id": "cfs_0000000000000000",
"rail": "pix-celcoin",
"currency": "BRL",
"status": "active",
"provider": "celcoin",
"provider_balance_minor": 999999,
"provider_error": null,
"as_of": "2026-09-10T12:00:01.000Z",
"pix_key": "a1b2c3d4-0000-4000-8000-000000000000",
"pix_key_type": "EVP",
"account_masked": "****1234"
}
]
}
```
`balances[]` is the balance: one entry per currency (`currency`, `balance_minor`, `available_minor`, `updated_at`), read from the same row `GET /v1/wallets/:id` returns and the figure every spend is validated against. `wallet_id` is `null` and `balances` is empty when the consumer has no wallet in this project yet; `balance` never creates one.
`funding_sources[]` lists the project's funding sources, each with `provider` (`celcoin`), `provider_balance_minor` (the provider's live balance, for reconciliation only, never the figure to decide a spend on), `provider_error` and `as_of`, plus the registered Pix key (`pix_key`, `pix_key_type`, `account_masked`). When the provider could not be read, `provider_balance_minor` is `null` and `provider_error` says why: `provider_unavailable` (asked, no readable answer) or `source_inactive` (the source is not active or has no account, so the provider was not asked); `balances[]` is unaffected either way. A funding source no longer carries `balance_minor`: that name used to hold the provider figure and read as the balance, and it was removed on purpose.
## When to use
- **Before a spend**, to know whether the wallet can cover it: `balance`.
- **To fund the wallet**: `receive` mints a Pix copia-e-cola (static by default, dynamic with `dynamic: true`) that a payer settles; the credit lands when the inbound webhook confirms. Show the code to the payer and re-read `balance` afterwards.
- **To reconcile**: `statement` is the wallet ledger (funds, holds, debits), newest first, up to `limit` entries.
Every action is scoped to one consumer; `consumer_id` defaults to the session user and is the same id [`codespar_shop`](/docs/concepts/meta-tools/shop) and `codespar_pay` use.
## Arguments
| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | No | `balance` \| `statement` \| `receive`. Defaults to `balance`. |
| `consumer_id` | `string` | No | Whose wallet; defaults to the session user |
| `amount` | `number` | No | Top-up amount in minor units (centavos for BRL), for `receive` |
| `description` | `string` | No | Charge description shown to the payer (`receive`) |
| `dynamic` | `boolean` | No | `receive`: mint a dynamic copia-e-cola (location URL) instead of a static QR. Default `false` |
| `limit` | `number` | No | Max ledger entries, 1..100, default 20 (`statement`) |
## Errors and what to do
| Error | Cause | What to do |
|---|---|---|
| `invalid_args` | An unknown `action`. Nothing is read or minted. | Fix the call against the Arguments table. |
| A wallet with no funding source | The consumer has no payment account yet (in live, an account comes from [`codespar_kyc`](/docs/concepts/meta-tools/kyc) `onboarding`). | Onboard the consumer first. In the test environment the sandbox wallet ships pre-connected. |
## Money and mandate
Nothing on this tool moves money by itself. `receive` creates an instrument (the copia-e-cola) that a payer settles later; the wallet is credited only when the inbound webhook confirms the payment. Spending out of the wallet happens on `codespar_pay`, and every spend is mandate-gated server-side (per-currency caps, per-transaction caps, allowlists, expiry). The wallet holds the funds; the [mandate](/docs/concepts/mandates) holds the permission.
## Related
- [`codespar_pay`](/docs/concepts/meta-tools/pay): spend out of the wallet
- [`codespar_shop`](/docs/concepts/meta-tools/shop): buy at real stores; the checkout's Pix is paid from this wallet
- [`codespar_kyc`](/docs/concepts/meta-tools/kyc): `onboarding` provisions the account this wallet is funded from
- [Wallets concept](/docs/concepts/wallets): account wallets vs consumer wallets, invariants, reconciliation
- [Consumer wallet API](/docs/api/reference/wallets#consumer-wallets-multi-slot-mandate-wallet): REST endpoints, including slot transfer
- [Shopping Agent cookbook](/docs/cookbooks/shopping-agent): the balance a shopper's agent spends from
## Notes
**The multi-slot wallet.** A consumer's wallet is one wallet with per-currency slots (for example `BRL` and `USDC`) minted from a single mandate signature. There is no FX inside the wallet: each slot has its own cap and settled-spend ledger, and the payee type routes a payment to the matching slot (a URL or `0x` address routes to `USDC`; a Pix key or copia-e-cola routes to `BRL`). Moving balance between slots is a REST operation, documented in the [consumer wallet API](/docs/api/reference/wallets#consumer-wallets-multi-slot-mandate-wallet).
**Fund, check, spend.** `receive` with an `amount` → the payer settles the copia-e-cola → the webhook credits the wallet → `balance` shows the funds → `codespar_pay` spends them under the signed mandate. The settlement's receipt is the Control Record, mandate, payment and delivery bound in one signed document: