codespar_wallet

This 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

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

const result = await session.execute("codespar_wallet", {
  action: "balance",
  consumer_id: "consumer_0000"
});

result = session.execute("codespar_wallet", {
  "action": "balance",
  "consumer_id": "consumer_0000"
})

codespar tool codespar_wallet \
  -i '{
       "action": "balance",
       "consumer_id": "consumer_0000"
     }'

{
  "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"
    }
  ]
}

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 and codespar_pay use.

Arguments

Errors and what to do

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 wallet
• codespar_shop: buy at real stores; the checkout's Pix is paid from this wallet
• codespar_kyc: onboarding provisions the account this wallet is funded from
• Wallets concept: account wallets vs consumer wallets, invariants, reconciliation
• Consumer wallet API: REST endpoints, including slot transfer
• Shopping Agent cookbook: 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.

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: