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. With a period (from and to, or days) it answers the statement the dashboard shows instead: one line per operation, the period's opening, inflows, outflows and closing, and next_cursor for the next page.
• To manage the account's Pix keys from a conversation: pix_keys_list, pix_keys_register, pix_keys_delete (see Pix keys below). None of them moves money.

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
• cs.wallet.pixKeys: the same Pix key operations over the REST routes, in the SDK
• 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:

Pix keys

The account's Pix keys, shaped for a conversation. pix_keys_list answers each key as key_id, key_type and key_tail (its last four characters), with count, can_register and can_delete; the full key never travels in a result, the person copies it on the dashboard page panel_url names (the Wallet page of the project, or the customer account's page). pix_keys_register registers one key: in the test environment always a random key (EVP), whatever key_type says; in live, key_type and key as the REST route takes them. pix_keys_delete takes a key_id from the list and confirm: without confirm: true it answers status: "requires_confirmation" with the key's tail and the consequence sentence (consequence, in Portuguese: once deleted, the key no longer points to this account), and sends nothing; the agent asks the person and calls again with confirm: true.

{
  "action": "pix_keys_list",
  "status": "ok",
  "consumer_id": "sbx_prj_0000000000000000",
  "account_masked": "••••27",
  "keys": [{ "key_id": "pk_0000000000000000abcd", "key_type": "EVP", "key_tail": "e0e4" }],
  "count": 1,
  "can_register": true,
  "register_type": "EVP",
  "can_delete": false,
  "delete_reason": "only_key",
  "panel_url": "/dashboard/projects/prj_0000000000000000/wallets"
}

The rules the dashboard panel applies hold here too. The account keeps at least one key (can_delete: false with delete_reason: "only_key", and pix_key_only_key on a delete). A customer account paused in CodeSpar still lists and refuses the writes (blocked_paused); a closed binding or a closed space refuses both (binding_closed, space_closed). status: "not_found" (not this account's key now) and status: "already_deleted" (the bank says the entry was already gone) are answers, never errors, so a repeated deletion is harmless. Every bank call for a test project's own account counts in the project's call budget, as the panel's calls do.

consumer_id defaults to the session user; in a test project whose session user has no account of its own, to the project's own account (sbx_<projectId>), the one the Wallet page shows. The same three operations exist as REST routes (/v1/consumers/:consumerId/pix-keys), in the SDK (cs.wallet.pixKeys) and in the CLI (codespar pix-keys); those answer the key value, because the caller there is the account's operator and not a model reading a tool result.

Documents

Documents on demand, generated from confirmed data and never from a new operation. receipt_document takes the receipt_id of a payment and answers the reference of its comprovante: filename, content_type, sha256 (the hash of the structured data the page was rendered from, the same value the REST route sends in X-CodeSpar-Document-Sha256) and path, the authenticated API path of the bytes (/v1/consumers/receipts/{id}/document?format=pdf|png); the chat and the dashboard turn that path into a download, and nothing in the result is a public link. format: "png" answers the same page as an image, for a conversation. Before the payment is confirmed the action answers status: "refused" with document_not_final: the receipt reflects the confirmed state and the data available, not a promise. statement_document takes from and to (YYYY-MM-DD, at most 92 days, to not after today) and answers the reference of the account statement (extrato) as an A4 PDF: totals with opening_minor, inflows_minor, outflows_minor, closing_minor and reserved_minor, where the first four close the identity opening + inflows − outflows = closing (asserted on the server against an independent reading of the ledger; a period that does not close answers statement_not_reconciled, never a wrong page) and the reserves (holds) stay apart from it. A test project's documents carry the Test mark once, in the header; a statement is always pdf.

{
  "action": "receipt_document",
  "status": "ok",
  "document": {
    "kind": "receipt",
    "format": "pdf",
    "filename": "comprovante-rcpt_0000000000000000.pdf",
    "content_type": "application/pdf",
    "sha256": "9f2c…",
    "path": "/v1/consumers/receipts/rcpt_0000000000000000/document?format=pdf",
    "environment": "test",
    "receipt_id": "rcpt_0000000000000000",
    "amount_minor": 12500,
    "currency": "BRL"
  }
}

The same two documents exist as REST routes (GET /v1/consumers/receipts/{id}/document, GET /v1/account/statement), in the SDK (cs.receipts.document, cs.account.statement), in the CLI (codespar receipts document, codespar account statement) and, in the stdio server, as the codespar_documents tool; those answer the bytes, because the caller there is the account's operator. The renderer is the platform's own headless browser, with no network and no scripts; while it is down the routes answer 503 document_renderer_unavailable and the dashboard keeps the download links in place.