codespar_wallet
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.
The agent's governed funds: balance, statement, top-up; per-currency slots.
codespar_wallet3 actionsmoves no moneyalways required actionThis is the wallet the agent spends FROM. Fund it with receive, then spend with codespar_pay. It is distinct from codespar_ledger, the double-entry books.
Actions
action | What it does | Money | Needs |
|---|---|---|---|
balanceexample below | Read the spendable balance and the Pix key bound to the wallet (the default action) | no | — |
statement | Read the wallet ledger: funds, holds and debits, newest first | no | — |
receive | Mint a Pix copia-e-cola a payer settles to top the wallet up; the credit lands when the inbound webhook confirms | no | — |
Unknown action: refused; nothing is read or minted. Measured 2026-09-09.
Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.
Example
action: "balance", the default: the spendable funds and the Pix key bound to the wallet.
{
"name": "codespar_wallet",
"arguments": {
"action": "balance",
"consumer_id": "consumer_0000"
}
}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.
When to use
- Before a spend, to know whether the wallet can cover it:
balance. - To fund the wallet:
receivemints a Pix copia-e-cola (static by default, dynamic withdynamic: true) that a payer settles; the credit lands when the inbound webhook confirms. Show the code to the payer and re-readbalanceafterwards. - To reconcile:
statementis the wallet ledger (funds, holds, debits), newest first, up tolimitentries.
Every action is scoped to one consumer; consumer_id defaults to the session user and is the same id codespar_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 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 holds the permission.
Related
codespar_pay: spend out of the walletcodespar_shop: buy at real stores; the checkout's Pix is paid from this walletcodespar_kyc:onboardingprovisions the account this wallet is funded from- Wallets concept: account wallets vs consumer wallets, invariants, reconciliation
- Consumer wallet API: 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.
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:
codespar_shop
Buy-side shopping. Act as the shopper, search a store's live catalog and buy, minting the store's real Pix copia-e-cola to settle from the governed wallet. VTEX guest checkout and Mercado Livre.
codespar_pay
Outbound spend. Money leaves the wallet or account your agent governs, under a signed mandate. Pix, card, boleto settlement, TED and wire, plus the reads around them (status, boleto quote, DDA, DICT keys and claims, Pix devolution).