---
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";

<MetaToolHeader tool="codespar_wallet" />

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

<MetaToolActions tool="codespar_wallet" />

## Example

`action: "balance"`, the default: the spendable funds and the Pix key bound to the wallet.

<Split min={380}>
<SplitPane label="Call · tools/call">

```json title="arguments"
{
  "name": "codespar_wallet",
  "arguments": {
    "action": "balance",
    "consumer_id": "consumer_0000"
  }
}
```

</SplitPane>
<SplitPane label="Result">

Result shape: see runtime. The tool document says `balance` returns the wallet balance plus its Pix key (the spendable funds), and names no field for either. Call it in the test environment, where the sandbox wallet ships pre-connected, to see the fields; the published document is [`/v1/meta-tools.json`](https://api.codespar.dev/v1/meta-tools.json).

</SplitPane>
</Split>

## 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/directed-pay) 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/wallets#consumer-wallets-multi-slot-mandate-wallet): REST endpoints, including slot transfer

## 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/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:

<ReceiptCard />