codespar_ledger

Double-entry ledger. Record money movement, read balances, create accounts, and read the signed agentic receipt of a spend. Routes to the tenant's self-hosted Lerian Midaz; the books, not the money.

Shared railUsed by buy-side and sell-side agents alike; not tied to a money direction.

Double-entry books plus the signed agentic receipts.

tool codespar_ledger5 actionsmoves no moneyalways required action

The system of record. codespar_pay and codespar_charge move real money through PSPs; the ledger records what happened, immutably and auditably, on the tenant's own Lerian Midaz instance.

Actions

`action`	What it does	Money	Needs
`entry` example below	Post an n:n journal entry (the default); source debits must equal destination credits	no	`sourcedestinationasset`
`balance`	Read an account's balances	no	`account`
`account`	Create a ledger account with an alias and a Midaz type	no	`aliasname`
`receipt`	Read one agentic receipt (mandate, quote, payment, delivery with its chain hash) by receipt_id	no	`receipt_id`
`receipts`	List a consumer's receipts, newest first	no	—

Unknown action: refused; nothing is posted. 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: "entry", the default: a journal entry moving R$ 150,00 from a wallet account to a revenue account. Amounts are in minor units, with a per-asset scale.

Call · tools/call

arguments

{
  "name": "codespar_ledger",
  "arguments": {
    "action": "entry",
    "asset": "BRL",
    "scale": 2,
    "source": [{ "account": "@wallet/consumer_0000", "amount": 15000 }],
    "destination": [{ "account": "@revenue/store_0000", "amount": 15000 }],
    "description": "Example order settled"
  }
}

Result

Result shape: see runtime. The tool document says receipt returns the Control Record (mandate → quote → payment → delivery, with a tamper-evident chain hash and any settle-time exceptions) and names no field for any action. The published document is /v1/meta-tools.json.

When to use

Recording a settlement in your own books after a charge or payout: entry, with source debits equal to destination credits.
Reading a balance or opening an account: balance by account UUID; account with an alias such as @wallet/consumer_0000, a display name and a Midaz type.
Answering "what did this agent actually settle, and under which mandate": receipt by receipt_id, or receipts for a consumer, newest first. These read the signed receipt store, not the journal, and every receipt read is itself audited.

The ledger is asset-agnostic: no currency or country routing, and multi-asset (BRL, USD, USDC, ...) with a scale per asset.

Arguments

Field	Type	Required	Description
`action`	`string`	No	`entry` (default) \| `balance` \| `account` \| `receipt` \| `receipts`
`source`	`array`	For `entry`	Debit side(s): `[{ account (alias), amount (minor units) }]`
`destination`	`array`	For `entry`	Credit side(s), same shape. Debits must equal credits
`asset`	`string`	For `entry`, `account`	Asset or currency code: `BRL`, `USD`, `USDC`, ...
`scale`	`number`	No	Decimal places for the asset. Default 2; JPY is 0, most crypto 6 or 8
`description`	`string`	No	Transaction description (`entry` only)
`account`	`string`	For `balance`	Account UUID to read balances for
`alias`	`string`	For `account`	Account alias, e.g. `@wallet/user_123`
`name`	`string`	For `account`	Account display name
`type`	`string`	No	Midaz account type: `deposit` (default), `savings`, `external`
`receipt_id`	`string`	For `receipt`	The agentic receipt id (`rcpt_...`)
`consumer_id`	`string`	No	Whose receipts to list (`receipts`). Defaults to the session user
`limit`	`number`	No	Max receipts to list (`receipts`), default 50
`metadata`	`object`	No	Free-form metadata stored on the entry or account

Errors and what to do

Error	Cause	What to do
`invalid_args`	An `entry` whose debits do not equal its credits, a `balance` without `account`, an `account` without `alias`, an unknown `action`. Nothing is posted.	Fix the call against the Arguments table.
`no_eligible_providers`	The tenant's Midaz instance is not connected on this project.	Connect it once in `/dashboard/auth-configs` (see Notes).
A receipt not found	`receipt_id` is not a receipt of this consumer's organization.	Check the id from the payment result; receipts are scoped to the caller's organization.

Money and mandate

No money moves on this tool: an entry is a record, and a wrong entry is corrected by a reversing entry, never by editing. receipt and receipts are how an operator or auditor reads back the mandate a spend ran under; the receipt is the Control Record described under audit chain, signed and chain-hashed.

codespar_pay and codespar_charge: the money the ledger records
codespar_wallet: the governed balance, whose settlement receipt this tool reads
Audit chain: the Control Record and its chain hash
Agent with a Wallet cookbook: wallet balances backed by a ledger

Notes

Operator setup. The ledger is the tenant's own Midaz instance. The operator connects it once in /dashboard/auth-configs; credentials are stored in the vault. See Lerian Midaz for self-hosting.

From the SDK. session.ledger(args) is the typed wrapper; session.execute("codespar_ledger", arguments) takes the same arguments as the MCP call.

On this page