Reconcile Token Ledger
Record locally-consumed tokens as a usage_debit entry and return the caller's current token balance. Consumed by the mcpbundler daemon's spend-check middleware to refill its per-session token-bucket cache; called with consumed=0 for a pure balance read. Returns 200 for both a successful debit and a rejected one, reported as rejected=true with the unchanged balance, not recorded, and not surfaced as an HTTP error status. A debit is rejected either because it would take the balance negative, or because the deployment this token belongs to has billing paused (its owner's membership in the organisation it bills has ended), in which case no debit is attempted at all. See responses below for the two outcomes that are HTTP errors.
Authorization
BundleAccessToken In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Tokens spent since the caller's last reconcile, and what kind of activity produced them.
consumed=0 is the expected shape for a pure balance read (used once per session/run, at cold start, before any billable activity has happened yet). consumption_type is required so this M2M endpoint can never be used to write a source other than the four debit categories it is meant for - grants, topups, and refunds each have their own dedicated, separately authorized call sites and must never be reachable here.
provider_id names the Provider whose credits_per_unit rate this debit
should convert consumed through - required for
tts_character_debit/stt_second_debit (see reconcile_ledger's own 422
validation, raises if that provider has no rate configured); optional
for llm_completion_debit, which converts through the named provider's
rate when it resolves to an LLM-kind provider with a configured rate,
and otherwise defaults to 1 raw unit = 1 credit; ignored entirely for
mcp_tool_debit, which always stays 1 raw unit = 1 credit.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/bundler/ledger/reconcile" \ -H "Content-Type: application/json" \ -d '{ "consumption_type": "llm_completion_debit" }'{ "balance": 0, "rejected": false}{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ]}