Budget Ledger
budget_ledgerBudget Ledger: atomically reserves reported USD spend across a run and its sub-agents. Returns allow/warn/block, remaining budget, retry storms and spend velocity. Call judge first, then reserve immediately before spending; honor block. This is cooperative accounting, not payment enforcement. Root cap and parent are immutable. Children inherit the root cap (send the same cap). event_id is the authoritative idempotency key; a custom HTTP key cannot override it. New event_id per attempted action; same event_id and body replays without reserving twice. No refunds or cap resets. Warn reservations count as spend. Limits: USD, six decimals, cap at most 1000000. Three matching actions in 60 seconds allowed; fourth blocked. Velocity warning at ten attempts/minute or more than 25% of cap/minute; 80% usage warns. Use action to distinguish operations at a merchant. Stored: IDs, keyed fingerprints and amounts, not raw action/merchant. Records persist until the API key is deleted; keyless records have no automatic expiry. $0.002 per call; shared 3 free calls per UTC day without a key (daily private IP namespace), plus 10/day with a free key. Anonymous scopes rotate daily; use a key for a persistent ledger/chain. Send the same Bearer key plus a payment header to keep the same ledger/chain after the allowance runs out.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"run_id": "<run_id>",
"event_id": "<event_id>",
"amount": "<amount>",
"cap": "<cap>",
"merchant": "<merchant>"
},
"name": "budget_ledger"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | Yes | ||
| action | No | ||
| amount | Yes | ||
| run_id | Yes | ||
| currency | No | ||
| event_id | Yes | ||
| merchant | Yes | ||
| parent_run_id | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spent | Yes | ||
| run_id | Yes | ||
| reasons | Yes | ||
| decision | Yes | ||
| event_id | No | ||
| replayed | No | ||
| reserved | Yes | ||
| request_id | No | ||
| retry_count | No | ||
| root_run_id | Yes | ||
| remaining_budget | Yes | ||
| velocity_per_minute | No |