---
title: codespar_wallet
description: The agent's governed funds — check balance and Pix key, read the wallet ledger, mint a Pix copia-e-cola to top up. Buy-side companion to codespar_pay.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

# codespar_wallet

<Callout title="Meta-tool" type="info">
**Buy-side.** Your agent is the spender: this is the wallet it spends FROM. `codespar_wallet` reads and funds the consumer's governed wallet — balance and Pix key, ledger statement, and top-up via a minted Pix copia-e-cola. Distinct from [`codespar_ledger`](/docs/concepts/meta-tools/ledger) (the double-entry books) and from [`codespar_pay`](/docs/concepts/meta-tools/pay) (spending OUT). Fund with `receive`, then spend with `codespar_pay`.
</Callout>

## Actions

| `action` | Purpose |
|---|---|
| `balance` *(default)* | The spendable funds: wallet balance + the Pix key bound to it |
| `statement` | The wallet ledger (funds, holds, debits), newest first |
| `receive` | Mint a Pix copia-e-cola a payer pays to TOP UP the wallet; settlement credits the wallet via the inbound webhook |

## Arguments

| Field | Type | Description |
|---|---|---|
| `action` | `string` | `balance` \| `statement` \| `receive` (default `balance`) |
| `consumer_id` | `string?` | Whose wallet; defaults to the session user |
| `amount` | `number?` | Top-up amount in minor units (centavos for BRL); `action=receive` |
| `description` | `string?` | Charge description shown to the payer; `action=receive` |
| `dynamic` | `boolean?` | `action=receive`: mint a DYNAMIC copia-e-cola (location URL) instead of a static QR. Default `false` |
| `limit` | `number?` | Max ledger entries (1..100, default 20); `action=statement` |

## The multi-slot wallet

A consumer's wallet is ONE wallet with per-currency slots (for example `BRL` + `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`). The REST surface behind this tool is documented in the [consumer wallet API](/docs/api/wallets#consumer-wallets-multi-slot-mandate-wallet), including moving balance between slots.

## Example flow (fund, check, spend)

```text
1. codespar_wallet action=receive amount=15000 description="Top up"
   → { pix_copia_e_cola: "00020126...", ... }   ← payer pays this
2. (webhook settles → wallet credited)
3. codespar_wallet action=balance
   → { balance, pix_key, ... }
4. codespar_pay recipient=<pix key or copia-e-cola> amount=...
   → spend, gated by the signed mandate
```

The settlement's receipt is the Control Record: mandate, payment and delivery bound in one signed document:

<ReceiptCard />

<Callout type="info">
Every spend out of the wallet 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.
</Callout>

## Related

- [`codespar_shop`](/docs/concepts/meta-tools/shop) — buy at real stores; the checkout's Pix code is paid from this wallet
- [`codespar_pay`](/docs/concepts/meta-tools/pay) — spend out of the wallet
- [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 incl. slot transfer