codespar_wallet
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.
codespar_wallet
Meta-tool
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 (the double-entry books) and from codespar_pay (spending OUT). Fund with receive, then spend with codespar_pay.
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, including moving balance between slots.
Example flow (fund, check, spend)
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 mandateThe settlement's receipt is the Control Record: mandate, payment and delivery bound in one signed document:
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 holds the permission.
Related
codespar_shop— buy at real stores; the checkout's Pix code is paid from this walletcodespar_pay— spend out of the wallet- Wallets concept — account wallets vs consumer wallets, invariants, reconciliation
- Consumer wallet API — REST endpoints incl. slot transfer
codespar_shop
Buy-side shopping — act as the shopper to search a store's catalog and buy a product, minting the store's real Pix. VTEX guest checkout and Mercado Livre. Call via session.execute().
codespar_pay
Outbound spend. Money leaves the wallet or account your agent governs. 26 provider rails across BR (incl. 9 banks direct via mTLS), MX, PE, CL, CO, and international card/wire.