Money

Six commands in the codespar binary touch money. Two run against a charge you issue (charge, payment-status), three against a consumer's mandate wallet (wallet, spend, transfer), and one against the tenant's own double-entry books (ledger).

Every flag, argument, message and exit code below was run against @codespar/cli 0.10.0 — the version on npm. The blocks labeled stdout and stderr are the captured bytes of those runs, with the two streams kept apart; the ids and amounts in them are from a test project.

The argument schema of codespar_charge and codespar_ledger belongs to the server: the CLI checks a handful of fields and forwards the rest of your object untouched, so the field lists below are the CLI's checks, not the tool's full schema. A call the CLI accepts can still be refused upstream, with the tool's own message.

Before any of them

Credentials and scope resolve the same way for all six: a command-line flag beats an environment variable, which beats ~/.codespar/config.json. The flags are --api-key <key>, --base-url <url> and --project <id>; the variables are CODESPAR_API_KEY, CODESPAR_PROJECT and CODESPAR_BASE_URL. With nothing set, the base URL is https://api.codespar.dev. When no key resolves, each of the six refuses before touching the network:

✗ Not logged in. Run `codespar login` or set CODESPAR_API_KEY.

--json is declared on the root command, and Commander accepts it on either side of the subcommand: codespar --json wallet consumer_0000 and codespar wallet consumer_0000 --json printed the same document. Tables, key/value blocks and JSON go to stdout; the ✓, ℹ and ⚠ lines go to stderr, so a pipe into jq gets the data alone.

Two clients, and why failures look different

wallet, spend and transfer call the REST API through the CLI's own HTTP client. charge, ledger and payment-status go through the SDK, which opens a session first. The split is invisible while things work and decides everything when they fail: the HTTP client turns a non-2xx into a one-line CLI refusal, and the SDK throws an error type the CLI does not recognize as its own.

The six split by direction. charge and payment-status pull money in, so they sit on the sell side. spend and transfer push it out, on the buy side, and transfer plans the move and sends nothing until you add --execute. wallet and ledger move nothing on a rail: wallet reads the caps and what is left, ledger writes to the tenant's own double-entry books.

codespar charge

Opens a throwaway session with no server pinned, calls the codespar_charge meta-tool with the JSON object you pass, prints the result, and closes the session in a finally. The router picks the rail, so there is no --server to choose.

codespar charge (--input '<json>' | --input-file <path>) [--user <id>] [--json]

Five fields are checked in the CLI before any request leaves. amount must be a number in major units, so R$ 125.00 is 125. currency must be a non-empty string. method, buyer.name and description must be present. method is checked for presence only and not against a list, so whatever you write is what the server receives; the refusal text names pix | boleto | card.

codespar charge --input '{
  "amount": 150,
  "currency": "BRL",
  "method": "pix",
  "description": "Order 0000",
  "buyer": { "name": "Example Buyer", "email": "buyer@example.com" }
}'

✓ charge chg_0000 → pending
ℹ Amount: 150 BRL  ·  method: pix
ℹ Charge URL: https://sandbox.example.com/i/chg_0000
ℹ Pix QR (truncated): iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAABi...
ℹ Pix copy-paste:

00020126580014BR.GOV.BCB.PIX0136example-key5204000053039865802BR6009SAO PAULO62070503***6304ABCD

In human mode the copy-and-paste string is the only thing on stdout, printed between two blank lines, so redirecting stdout captures the payable string and nothing else from the run. The QR line on stderr is cut at 40 characters and is not the payload. Charge URL, the QR line and the copy-and-paste block print only when the result carries those fields. With --json, stdout gets the whole result object and stderr stays empty.

Calls the meta-tool over the session execute route:

The tool's actions, its providers and the full argument schema are on the codespar_charge page; the route's own gates and responses are on POST /v1/sessions/{id}/execute.

Refusals

codespar payment-status

Reads where the payment a tool call started got to. Without --stream it opens a session, reads the status once and closes it. With --stream it follows the server-sent event stream until the terminal frame, printing every update on the way.

codespar payment-status <tool-call-id> [--stream] [--timeout <ms>] [--user <id>] [--json]

--timeout is validated on every run and applied only to --stream: codespar payment-status tcl_0000 --timeout 0 is refused even with no stream requested. When the budget runs out, or you press Ctrl+C, the stream aborts and the command exits 1.

# read once
codespar payment-status tcl_0000

# follow until the terminal frame, capped at 30s
codespar payment-status tcl_0000 --stream --timeout 30000

✓ payment_status: succeeded
ℹ tool_call_id: tcl_0000
ℹ original_status: success
ℹ idempotency_key: idm_0000
ℹ events: 1

Nothing reaches stdout in human mode: those five lines are all stderr, and --json is what puts the envelope on stdout. original_status is the execute-time result and payment_status is the settlement state; they move independently, which is why both are printed. idempotency_key prints - when the call carried none. Under --stream without --json, each update becomes an ℹ update #N: payment_status=... events=N line on stderr before the same five-line ending.

Calls one of two routes, depending on --stream:

Both are in the HTTP reference: GET /v1/tool-calls/{id}/payment-status and the stream, including how the correlation key decides whether anything can be found at all.

Refusals

codespar wallet

Reads a consumer's unified wallet and prints one row per currency: what the agent is authorized to spend, what it has spent, and what is left. Caps are per currency and nothing converts between them.

codespar wallet <consumer> [--json]

The command declares no flags of its own; only the root flags apply.

codespar wallet consumer_0000

currency  rail          authorized  spent  available
BRL       pix-consent   50000       12500  37500
USDC      usdc-onchain  10000       12500  -2500 (overspent)

ℹ Amounts are in minor units (cents / micro-USDC). Caps are per-currency, no FX. A negative available marked (overspent) means settled debits exceed the cap.

available is authorized minus spent and is not floored at zero. When settled debits exceed the cap, the cell carries the literal suffix (overspent) next to the negative number, so a minus sign is not the only signal. A consumer with no active slots prints a hint instead of a table, on stderr, and still exits 0:

ℹ No active mandate slots for consumer consumer_empty.
  Create one with: codespar mandate create --consumer consumer_empty --slot USDC:usdc-onchain:100:100 ...

Calls

Field meanings and the full response are on GET /v1/consumers/{id}/wallet; the slot model and the current rail status are under Consumer wallets.

Refusals

codespar spend

Executes a payment inside an existing signed mandate. The CLI sends three values and reads none of the answer: the backend reconstructs the stored mandate, runs the cap and allowlist gates, and picks the rail from the shape of the payee.

codespar spend --mandate <id> --payee <payee> --amount <minor> --agent <id> [--json]

All four are required options, so Commander refuses a missing one before the command body runs. The CLI does not inspect --payee: it forwards the string, and the rail is chosen server-side. The command's source records the mapping it expects, a Pix key or copy-and-paste string to Pix, an EVM address to a USDC transfer, an http(s) URL to x402; the route reference is where that behaviour is documented and kept honest.

codespar spend \
  --mandate cm_0000 \
  --payee vendedor@example.com.br \
  --amount 2500 \
  --agent agt_0000

✓ spend executed
ℹ The on-chain tx / receipt is in the response below:

{
  "spend_id": "spd_0000",
  "mandate_id": "cm_0000",
  "amount_minor": 2500,
  "rail": "pix",
  "status": "settled",
  "provider_tx_id": "pix_0001",
  "receipt_id": "rcpt_0000"
}

The response body goes to stdout in both modes. --json only suppresses the two stderr lines, so a script parses the same stdout either way. The fields in that block are whatever the route returned; the CLI prints the body as it arrives.

Calls

The gates that refuse this call and the meaning of each refusal are on POST /v1/consumers/mandates/{id}/spend.

Refusals

codespar transfer

Moves value between two currency slots of one consumer's wallet. There is no FX inside the wallet, so a cross-currency move is a real trade through the ramp. Without --execute the call plans the move and moves nothing.

codespar transfer <consumer> --from <currency> --to <currency> --amount <minor> [--execute] [--agent <id>] [--purpose <text>] [--json]

The human output has two shapes, and the flag is not what chooses between them: the CLI branches on the response's executed field. A plan prints a key/value block headed by Transfer plan for <consumer>; an execution prints transfer executed (<route>) and a different set of rows.

codespar transfer consumer_0000 --from BRL --to USDC --amount 15000

codespar transfer consumer_0000 --from BRL --to USDC --amount 15000 --execute

route       onramp
converts    yes — via transfero at the real rate (no FX)
executable  yes
from        BRL/pix-consent (cap left 37500)
to          USDC/usdc-onchain
amount      15000 (minor)

consumer      consumer_0000
route         onramp via transfero (real rate, no FX)
onramp tx     ftx_0000
status        processing
destination   0x0000000000000000000000000000000000000000
source debit  pix_0000 (settled)

On the plan run, stderr carried ℹ Transfer plan for consumer_0000:, the response's own note, and the ready-made command line to run it for real. On the execute run it carried ✓ transfer executed (onramp) and, because that response named a settle_via path, a line saying the credit settles asynchronously and pointing at codespar wallet <consumer> to watch it. A response carrying source_debit_error adds a ⚠ line saying the source debit did not complete; the source debit row and the async line both depend on fields the response may omit.

Calls

The body, the plan-versus-execute contract, the matrix of which routes execute today and the error codes for the rest are under Consumer wallets.

Refusals

codespar ledger

Posts a double-entry transaction, reads an account's balances, or creates an account, against the tenant's own ledger. Like charge, it opens a throwaway session with no server pinned, calls the codespar_ledger meta-tool, and closes the session in a finally.

codespar ledger (--input '<json>' | --input-file <path>) [--user <id>] [--json]

The CLI accepts three actions and checks one or three fields for each, before the network:

Anything else is refused with ledger.action must be one of: entry, balance, account., including the receipt-reading actions that the tool's TypeScript argument type carries: the CLI's list is narrower than the type's, measured by sending action: "receipt" and getting that refusal. Every field outside that table goes to the server unchecked.

codespar ledger --input '{
  "action": "entry",
  "asset": "BRL",
  "source": [{ "account": "@external/BRL", "amount": 12500 }],
  "destination": [{ "account": "@wallet/user_0000", "amount": 12500 }],
  "description": "top-up"
}'

✓ ledger entry → APPROVED
ℹ Id: txn_0000

Id, Account and Alias print only when the result carries them, and an entry writes nothing to stdout. action: "balance" is the one shape that does: the balances are dumped there as indented JSON, under an ℹ Balances: line on stderr. With --json, stdout carries the whole result and stderr stays empty.

Calls the meta-tool over the same session execute route as charge:

The actions, the ledger behind them and the full argument schema are on the codespar_ledger page.

Refusals

Next