AgentLedger is an MCP server published by io.github.entradox, hosted at aiagentscity.com. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 18 tools, including ledger_rotate_secret, ledger_revoke_secret, ledger_track, ledger_set_budget, ledger_report.
Meter, cap, and block AI agent spend before the provider is charged.
14 connections through 5 shared values. Tap any node.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Mint a NEW agent_secret for an agent_id your workspace already owns, invalidating the old one. Use this to RECOVER an agent whose secret was lost: the previous credential stops working immediately. Requires the workspace_key that owns agent_id — an agent's own agent_secret cannot rotate itself, because a leaked agent credential must not be able to lock its real owner out. Unlike ledger_track this never claims a new agent_id: an unknown id returns agent_not_claimed. The new secret is returned ONCE. Store it before you drop the response. Returns {"agent_id", "agent_secret", "_note"}, or {"error", "error_code"}.
| Parameter | Type | Description |
|---|---|---|
| agent_id * | string | |
| workspace_key * | string |
{
"name": "ledger_rotate_secret",
"title": "Rotate Agent Secret",
"description": "Mint a NEW agent_secret for an agent_id your workspace already owns, invalidating the old one.\n\nUse this to RECOVER an agent whose secret was lost: the previous credential\nstops working immediately. Requires the workspace_key that owns agent_id —\nan agent's own agent_secret cannot rotate itself, because a leaked agent\ncredential must not be able to lock its real owner out. Unlike ledger_track\nthis never claims a new agent_id: an unknown id returns agent_not_claimed.\n\nThe new secret is returned ONCE. Store it before you drop the response.\n\nReturns {\"agent_id\", \"agent_secret\", \"_note\"}, or {\"error\", \"error_code\"}.",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"workspace_key"
],
"properties": {
"agent_id": {
"type": "string"
},
"workspace_key": {
"type": "string"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Rotate Agent Secret",
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}Invalidate an agent_id's agent_secret WITHOUT deleting its spend history. Use when a credential may have leaked, or to stop an agent writing. Subsequent writes to that agent fail with agent_secret_mismatch until you rotate a new secret in. The agent_id stays claimed, so no other workspace can claim it and inherit the ledger. Requires the workspace_key that owns agent_id. Returns {"agent_id", "revoked": True, "_note"}, or {"error", "error_code"}.
| Parameter | Type | Description |
|---|---|---|
| agent_id * | string | |
| workspace_key * | string |
{
"name": "ledger_revoke_secret",
"title": "Revoke Agent Secret",
"description": "Invalidate an agent_id's agent_secret WITHOUT deleting its spend history.\n\nUse when a credential may have leaked, or to stop an agent writing.\nSubsequent writes to that agent fail with agent_secret_mismatch until you\nrotate a new secret in. The agent_id stays claimed, so no other workspace\ncan claim it and inherit the ledger. Requires the workspace_key that owns\nagent_id.\n\nReturns {\"agent_id\", \"revoked\": True, \"_note\"}, or {\"error\", \"error_code\"}.",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"workspace_key"
],
"properties": {
"agent_id": {
"type": "string"
},
"workspace_key": {
"type": "string"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Revoke Agent Secret",
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}Record a spend entry for an AI agent on any payment rail, with optional token counts. Claiming a brand-new agent_id requires your workspace_key (get one via x402 at POST /v1/billing/x402 — no human, no login — or at /start). That first call mints an agent_secret and returns it in the response — save it, every later call for that same agent_id must pass it back (no workspace_key needed again) or the write is rejected. Amounts are capped at $100,000/entry and must be >= 0. If a budget is set for this agent, an entry that would cross the monthly/daily cap is blocked, not just logged. Caps here bind the AMOUNT YOU REPORT — a caller that lies to amount_cents lies to the cap. The only enforcement against real spend is routing the provider call through the /proxy/{provider} rail, which prices from the provider's own usage block. Include tokens_in/tokens_out + model on every LLM call so token burn shows up in the /v1/tokens report.
| Parameter | Type | Description |
|---|---|---|
| rail * | string | payment rail used — one of "mpp", "x402", "api_key", "manual" |
| model | string | model name (e.g. "gpt-4o") — token burn is reported per model |
| service * | string | what was purchased (e.g. "search_query", "data_export") |
| agent_id * | string | unique agent identifier (e.g. "research-agent-v2") |
| tokens_in | integer | prompt tokens consumed (0 if unknown) |
| tokens_out | integer | completion tokens consumed (0 if unknown) |
| agent_secret |
Set spending caps for an agent. Warns at 80%, blocks spend when exceeded — enforced: a ledger_track call that would cross the cap is rejected. Dollar caps (monthly_cents/daily_cents) and token caps (monthly_tokens/ daily_tokens) are independent dimensions: dollar caps only cover non-"tokens" rails, token caps only cover rail="tokens" bookkeeping rows (tokens_in/tokens_out). Set both if the agent uses both. Monthly cap is required; the rest are optional (0 = no limit). Overwrites any existing budget for the agent — with one rule: raising or removing an existing cap requires the workspace_key. An agent_secret can tighten its own caps but never loosen them; to grow an allowance the agent asks its owner (see ledger_request_approval). Claiming a brand-new agent_id requires your workspace_key; that first call mints an agent_secret (returned once — save it); later calls for that agent_id must pass the agent_secret back (no workspace_key needed again).
| Parameter | Type | Description |
|---|---|---|
| agent_id * | string | unique agent identifier |
| daily_cents | integer | daily spending cap in cents (0 = no daily cap) |
| agent_secret | string | required for every call after the first for this agent_id |
| daily_tokens | integer | daily token-burn cap (0 = no cap) |
| monthly_cents * | integer | monthly spending cap in cents |
| workspace_key | string | required when claiming a brand-new agent_id; not needed once the agent_id has been claimed |
Spend report for an agent over a rolling window. Returns total spend, breakdown by rail and by service, budget status (ok/warning/exceeded), detected anomalies, and entry count. Requires a credential: either the agent's own agent_secret or its workspace's workspace_key (same rule as GET /v1/report).
| Parameter | Type | Description |
|---|---|---|
| days | integer | report window in days (default 30) |
| agent_id * | string | unique agent identifier |
| agent_secret | string | the agent's own secret (either this or workspace_key) |
| workspace_key | string | the owning workspace's key (either this or agent_secret) |
{
"name": "ledger_report",
"title": "Agent Spend Report",
"description": "Spend report for an agent over a rolling window.\n\nReturns total spend, breakdown by rail and by service, budget status\n(ok/warning/exceeded), detected anomalies, and entry count.\n\nRequires a credential: either the agent's own agent_secret or its\nworkspace's workspace_key (same rule as GET /v1/report).",
"inputSchema": {
"type": "object",
"required": [
"agent_id"
],
"properties": {
"days": {
"type": "integer",
"default": 30,
"description": "report window in days (default 30)"
},
"agent_id": {
"type": "string",
"description": "unique agent identifier"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (either this or workspace_key)"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key (either this or agent_secret)"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Agent Spend Report",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Point your provider traffic at the proxy so budget caps are enforced BEFORE the provider is contacted, instead of being reported afterwards. This closes the gap where the brake was unreachable from MCP: an agent connected over MCP could record spend (ledger_track) but nothing could refuse a call. With this, the cap is enforced on every LLM call. Returns the base_url to use, the two headers to send, and the exact change for the OpenAI and Anthropic SDKs. Your provider credential is NOT part of this: it stays in Authorization / x-api-key and is only forwarded, never stored.
| Parameter | Type | Description |
|---|---|---|
| agent_id * | string | the agent whose budget the proxied calls are billed to |
| provider | string | which upstream to proxy: openai or anthropic |
| agent_secret | string | the agent's own secret (either this or workspace_key) |
| workspace_key | string | the owning workspace's key (either this or agent_secret) |
{
"name": "ledger_proxy_attach",
"title": "Attach the Budget-Enforcing Proxy",
"description": "Point your provider traffic at the proxy so budget caps are enforced\nBEFORE the provider is contacted, instead of being reported afterwards.\n\nThis closes the gap where the brake was unreachable from MCP: an agent\nconnected over MCP could record spend (ledger_track) but nothing could\nrefuse a call. With this, the cap is enforced on every LLM call.\n\nReturns the base_url to use, the two headers to send, and the exact change\nfor the OpenAI and Anthropic SDKs. Your provider credential is NOT part of\nthis: it stays in Authorization / x-api-key and is only forwarded, never\nstored.",
"inputSchema": {
"type": "object",
"required": [
"agent_id"
],
"properties": {
"agent_id": {
"type": "string",
"description": "the agent whose budget the proxied calls are billed to"
},
"provider": {
"type": "string",
"default": "openai",
"description": "which upstream to proxy: openai or anthropic"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (either this or workspace_key)"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key (either this or agent_secret)"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Attach the Budget-Enforcing Proxy",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Alert history for an agent: budget warnings (80% threshold) and spending spikes. Requires a credential: either the agent's own agent_secret or its workspace's workspace_key (same rule as GET /v1/alerts).
| Parameter | Type | Description |
|---|---|---|
| agent_id * | string | unique agent identifier |
| agent_secret | string | the agent's own secret (either this or workspace_key) |
| workspace_key | string | the owning workspace's key (either this or agent_secret) |
{
"name": "ledger_alerts",
"title": "Agent Budget Alerts",
"description": "Alert history for an agent: budget warnings (80% threshold) and spending spikes.\n\nRequires a credential: either the agent's own agent_secret or its\nworkspace's workspace_key (same rule as GET /v1/alerts).",
"inputSchema": {
"type": "object",
"required": [
"agent_id"
],
"properties": {
"agent_id": {
"type": "string",
"description": "unique agent identifier"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (either this or workspace_key)"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key (either this or agent_secret)"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Agent Budget Alerts",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Long-poll an agent's event feed — how an agent with no public URL receives alerts. Webhooks (POST /v1/webhooks) push events to a URL you own; an agent on stdio MCP cannot host one, so it waits here instead. Call this in a loop: the call holds open up to `timeout` seconds (max 30) and returns when events arrive or the wait lapses. `consumer_id` names this consumer durably — pick a stable one (e.g. "claude-code-main") and reuse it. Each call returns a `cursor`; pass it back on your next call once you have processed that batch — that is the ack. To get restart redelivery, also pass `client_instance` (your process id or any per-boot token) and `client_started` (when your process booted): when the pair changes, events that were served but never acked come back with `redelivered: true`, so nothing is lost to a crash between serve and process. (The stdio MCP server supplies its own pid/started automatically — hosted callers must opt in because the gateway cannot see the client's process.) Each event is an envelope: id (deterministic — dedupe on it), kind (alert.raised | budget.warning | budget.exceeded | anomaly.detected), summary, context (agent_id, alert_type, timestamp), alerts_since_last_write (how many alerts are stacked up since the agent's last spend write — use it to throttle escalation), redelivered. Requires a credential: either the agent's own agent_secret or its workspace's workspace_key (same rule as GET /v1/agents/{agent_id}/events/wait).
| Parameter | Type | Description |
|---|---|---|
| name | string | optional label for this consumer instance |
| cursor | any | line offset you have processed through (omit to continue) |
| timeout | any | seconds to hold the call open (default 5, max 30) |
| agent_id * | string | unique agent identifier |
| consumer_id |
Ask BEFORE you spend: may this agent spend this much right now? Returns allowed (true/false), a stable reason code (within_budget, over_monthly_cap, over_daily_cap, over_monthly_token_cap, over_daily_token_cap, no_budget_set, unpriced_model), a one-line message, the cost estimate, the price used (with its source and as_of date) and every budget window with cap, spent and remaining. Same decision the /proxy/{provider} gate enforces. Read-only: nothing is recorded or reserved, so record the spend with ledger_track afterwards. Give exactly one spend shape: amount_cents (any rail, e.g. an x402 purchase), OR model with tokens_in/tokens_out.
| Parameter | Type | Description |
|---|---|---|
| model | string | model id to price from tokens (instead of amount_cents) |
| agent_id * | string | the agent that would spend |
| tokens_in | integer | expected input tokens (with model) |
| tokens_out | integer | expected output tokens, e.g. your max_tokens (with model) |
| agent_secret | string | the agent's own secret (either this or workspace_key) |
| amount_cents | any | the spend in cents, if you already know it |
| workspace_key | string | the owning workspace's key (either this or agent_secret) |
Ask your workspace owner for a one-shot spend exception before a ledger_track that the cap would refuse. Creates a pending permit for exactly amount_cents on the given service. The owner (a human, or a supervisor agent holding the workspace_key) approves or denies it with ledger_approval_decide. An APPROVED permit is consumed by the next ledger_track for this agent whose amount fits inside it — the budget cap itself does not change. Permits expire after 1 hour undecided. Poll with ledger_approvals to see the decision. Claiming a brand-new agent_id requires workspace_key; otherwise pass the agent's agent_secret.
| Parameter | Type | Description |
|---|---|---|
| reason | string | why, one line — shown to the approver |
| service * | string | what the money is for (e.g. "openai:gpt-5 batch eval") |
| agent_id * | string | the agent asking for the exception |
| agent_secret | string | the agent's own secret (either this or workspace_key) |
| amount_cents * | integer | the spend to be approved, in cents |
| workspace_key | string | the owning workspace's key (either this or agent_secret) |
{
"name": "ledger_request_approval",
"title": "Request Spend Approval",
"description": "Ask your workspace owner for a one-shot spend exception before a\nledger_track that the cap would refuse.\n\nCreates a pending permit for exactly amount_cents on the given service.\nThe owner (a human, or a supervisor agent holding the workspace_key)\napproves or denies it with ledger_approval_decide. An APPROVED permit is\nconsumed by the next ledger_track for this agent whose amount fits inside\nit — the budget cap itself does not change. Permits expire after 1 hour\nundecided. Poll with ledger_approvals to see the decision.\n\nClaiming a brand-new agent_id requires workspace_key; otherwise pass the\nagent's agent_secret.",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"amount_cents",
"service"
],
"properties": {
"reason": {
"type": "string",
"default": "",
"description": "why, one line — shown to the approver"
},
"service": {
"type": "string",
"description": "what the money is for (e.g. \"openai:gpt-5 batch eval\")"
},
"agent_id": {
"type": "string",
"description": "the agent asking for the exception"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (either this or workspace_key)"
},
"amount_cents": {
"type": "integer",
"description": "the spend to be approved, in cents"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key (either this or agent_secret)"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Request Spend Approval",
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}List spend-approval permits — yours, or your whole workspace's.
| Parameter | Type | Description |
|---|---|---|
| state | string | optional filter: pending | approved | denied | consumed | expired |
| agent_id | string | list this agent's permits (needs agent_secret or workspace_key) |
| agent_secret | string | the agent's own secret (agent view) |
| workspace_key | string | the owning workspace's key — lists ALL its agents' permits when given alone |
{
"name": "ledger_approvals",
"title": "List Spend Approvals",
"description": "List spend-approval permits — yours, or your whole workspace's.",
"inputSchema": {
"type": "object",
"properties": {
"state": {
"type": "string",
"default": "",
"description": "optional filter: pending | approved | denied | consumed | expired"
},
"agent_id": {
"type": "string",
"default": "",
"description": "list this agent's permits (needs agent_secret or workspace_key)"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (agent view)"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key — lists ALL its agents'\n permits when given alone"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "List Spend Approvals",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Approve or deny a pending spend permit — workspace owner only. The agent's own agent_secret can REQUEST an approval but can never decide one: a credential that can approve its own requests is not a control. decision must be 'approve' or 'deny'; only pending permits can be decided. An approved permit is consumed by the agent's next ledger_track within its amount — it is a one-shot exception, not a raised cap.
| Parameter | Type | Description |
|---|---|---|
| agent_id * | string | the agent that requested the permit |
| decision * | string | 'approve' or 'deny' |
| approval_id * | string | the apr_ id from ledger_request_approval / ledger_approvals |
| workspace_key * | string | the key of the workspace that owns the agent |
{
"name": "ledger_approval_decide",
"title": "Approve or Deny a Spend Request",
"description": "Approve or deny a pending spend permit — workspace owner only.\n\nThe agent's own agent_secret can REQUEST an approval but can never decide\none: a credential that can approve its own requests is not a control.\ndecision must be 'approve' or 'deny'; only pending permits can be decided.\nAn approved permit is consumed by the agent's next ledger_track within\nits amount — it is a one-shot exception, not a raised cap.",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"approval_id",
"decision",
"workspace_key"
],
"properties": {
"agent_id": {
"type": "string",
"description": "the agent that requested the permit"
},
"decision": {
"type": "string",
"description": "'approve' or 'deny'"
},
"approval_id": {
"type": "string",
"description": "the apr_ id from ledger_request_approval / ledger_approvals"
},
"workspace_key": {
"type": "string",
"description": "the key of the workspace that owns the agent"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Approve or Deny a Spend Request",
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}What will this call cost? Priced from the same table the caps use. Exists because ledger_track requires the CALLER to supply amount_cents, so an agent whose spend is capped could under-report its own cost and stay under the cap. This returns the number the enforcement path would use, so an agent can report honestly (and plan before it spends). Cost = (tokens_in * in_rate + tokens_out * out_rate) / 1_000_000. If the model has cache rates, the standard in-rate is used, which is the conservative direction for a spend cap. Every price carries the source it came from and the date it was read, and `verified: false` means the number was NOT read off the provider's own pricing page. Treat an unverified price as an estimate, not a measurement.
| Parameter | Type | Description |
|---|---|---|
| model * | string | the model id you are about to call (e.g. gpt-4o, claude-sonnet-4) |
| tokens_in | integer | expected input tokens |
| tokens_out | integer | expected output tokens, e.g. your max_tokens |
{
"name": "ledger_price",
"title": "Price a Call Before You Make It",
"description": "What will this call cost? Priced from the same table the caps use.\n\nExists because ledger_track requires the CALLER to supply amount_cents, so an\nagent whose spend is capped could under-report its own cost and stay under\nthe cap. This returns the number the enforcement path would use, so an agent\ncan report honestly (and plan before it spends).\n\nCost = (tokens_in * in_rate + tokens_out * out_rate) / 1_000_000. If the\nmodel has cache rates, the standard in-rate is used, which is the\nconservative direction for a spend cap.\n\nEvery price carries the source it came from and the date it was read, and\n`verified: false` means the number was NOT read off the provider's own\npricing page. Treat an unverified price as an estimate, not a measurement.",
"inputSchema": {
"type": "object",
"required": [
"model"
],
"properties": {
"model": {
"type": "string",
"description": "the model id you are about to call (e.g. gpt-4o, claude-sonnet-4)"
},
"tokens_in": {
"type": "integer",
"default": 0,
"description": "expected input tokens"
},
"tokens_out": {
"type": "integer",
"default": 0,
"description": "expected output tokens, e.g. your max_tokens"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Price a Call Before You Make It",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Get a FREE AgentLedger workspace with no credential and no arguments — the MCP equivalent of opening POST /start in a browser. Call this FIRST if you have no credentials yet. Every other tool here (ledger_track, ledger_set_budget, ledger_report, ledger_alerts) needs a workspace_key or an agent_secret, so a caller arriving with neither must start here or it has nowhere to go. Takes NO arguments on purpose: the goal is zero friction. It returns a `workspace_key` (shown exactly once — it cannot be re-revealed, so store it before continuing) which you then send as `workspace_key` on your first ledger_track for a NEW agent_id. That first write returns the agent's own `agent_secret`, which authenticates every write after it. The free tier includes every rail, enforced budget caps, alerts, reports and the MCP server, capped at 3 agents per workspace. Minting is rate-limited per caller IP, the same limit the human door uses. Prefer to pay? POST /v1/billing/x402 with a wallet-signed payment needs no human and buys 24h of Pro (agent allowance per the live pass tier — see /pricing.md).
No parameters.
{
"name": "ledger_start",
"title": "Start a Workspace",
"description": "Get a FREE AgentLedger workspace with no credential and no arguments —\nthe MCP equivalent of opening POST /start in a browser.\n\nCall this FIRST if you have no credentials yet. Every other tool here\n(ledger_track, ledger_set_budget, ledger_report, ledger_alerts) needs a\nworkspace_key or an agent_secret, so a caller arriving with neither must\nstart here or it has nowhere to go.\n\nTakes NO arguments on purpose: the goal is zero friction. It returns a\n`workspace_key` (shown exactly once — it cannot be re-revealed, so store it\nbefore continuing) which you then send as `workspace_key` on your first\nledger_track for a NEW agent_id. That first write returns the agent's own\n`agent_secret`, which authenticates every write after it.\n\nThe free tier includes every rail, enforced budget caps, alerts, reports and\nthe MCP server, capped at 3 agents per workspace. Minting is rate-limited\nper caller IP, the same limit the human door uses.\n\nPrefer to pay? POST /v1/billing/x402 with a wallet-signed payment needs no\nhuman and buys 24h of Pro (agent allowance per the live pass tier — see\n/pricing.md).",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Start a Workspace",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}Self-serve documentation for AgentLedger — quickstart, MCP tools, REST endpoints, budget caps, error codes, and idempotency usage, as markdown.
| Parameter | Type | Description |
|---|---|---|
| topic | string | "quickstart" | "mcp" | "rest" | "budget" | "errors" | "idempotency" | "metering" | "events" | "all" (default "" == "all"). Unknown topics fall back to the full docs. |
{
"name": "ledger_api_docs",
"title": "AgentLedger API Docs",
"description": "Self-serve documentation for AgentLedger — quickstart, MCP tools, REST\nendpoints, budget caps, error codes, and idempotency usage, as markdown.",
"inputSchema": {
"type": "object",
"properties": {
"topic": {
"type": "string",
"default": "",
"description": "\"quickstart\" | \"mcp\" | \"rest\" | \"budget\" | \"errors\" | \"idempotency\" | \"metering\" | \"events\" | \"all\"\n (default \"\" == \"all\"). Unknown topics fall back to the full docs."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "AgentLedger API Docs",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Complete, runnable Python recipe for a common AgentLedger integration pattern.
| Parameter | Type | Description |
|---|---|---|
| pattern * | string | "python_tracking" | "budget_enforcement" | "weekly_report" | "retry_safe_writes" |
{
"name": "ledger_examples",
"title": "AgentLedger Recipes",
"description": "Complete, runnable Python recipe for a common AgentLedger integration\npattern.",
"inputSchema": {
"type": "object",
"required": [
"pattern"
],
"properties": {
"pattern": {
"type": "string",
"description": "\"python_tracking\" | \"budget_enforcement\" | \"weekly_report\" |\n \"retry_safe_writes\""
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "AgentLedger Recipes",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}List this product's skills. Each entry carries the SKILL.md URI, its name and description, verbatim frontmatter, and a per-file sha256 manifest. Read a body with `read_skill`.
No parameters.
{
"name": "skills_list_tool",
"title": "Skills List Tool",
"description": "List this product's skills. Each entry carries the SKILL.md URI,\nits name and description, verbatim frontmatter, and a per-file\nsha256 manifest. Read a body with `read_skill`.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
}
}Read a product skill file by its skill:// URI.
| Parameter | Type | Description |
|---|---|---|
| uri * | string | e.g. skill://<product>/<skill-name>/SKILL.md Get valid URIs from `skills_list_tool`. |
{
"name": "read_skill",
"title": "Read Skill",
"description": "Read a product skill file by its skill:// URI.",
"inputSchema": {
"type": "object",
"required": [
"uri"
],
"properties": {
"uri": {
"type": "string",
"description": "e.g. skill://<product>/<skill-name>/SKILL.md\n Get valid URIs from `skills_list_tool`."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
}
}Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
| string |
| required for every call after the first for this agent_id |
| amount_cents * | integer | spend amount in cents (100 = $1.00), 0-10000000 |
| workspace_key | string | required when claiming a brand-new agent_id; not needed once the agent_id has been claimed |
{
"name": "ledger_track",
"title": "Track Agent Spend",
"description": "Record a spend entry for an AI agent on any payment rail, with optional token counts.\n\nClaiming a brand-new agent_id requires your workspace_key (get one via\nx402 at POST /v1/billing/x402 — no human, no login — or at /start).\nThat first call mints an\nagent_secret and returns it in the response — save it, every later call\nfor that same agent_id must pass it back (no workspace_key needed again)\nor the write is rejected. Amounts are capped\nat $100,000/entry and must be >= 0. If a budget is set for this agent,\nan entry that would cross the monthly/daily cap is blocked, not just\nlogged. Caps here bind the AMOUNT YOU REPORT — a caller that lies to\namount_cents lies to the cap. The only enforcement against real spend is\nrouting the provider call through the /proxy/{provider} rail, which\nprices from the provider's own usage block. Include tokens_in/tokens_out + model on every LLM call so token\nburn shows up in the /v1/tokens report.",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"rail",
"amount_cents",
"service"
],
"properties": {
"rail": {
"type": "string",
"description": "payment rail used — one of \"mpp\", \"x402\", \"api_key\", \"manual\""
},
"model": {
"type": "string",
"default": "",
"description": "model name (e.g. \"gpt-4o\") — token burn is reported per model"
},
"service": {
"type": "string",
"description": "what was purchased (e.g. \"search_query\", \"data_export\")"
},
"agent_id": {
"type": "string",
"description": "unique agent identifier (e.g. \"research-agent-v2\")"
},
"tokens_in": {
"type": "integer",
"default": 0,
"description": "prompt tokens consumed (0 if unknown)"
},
"tokens_out": {
"type": "integer",
"default": 0,
"description": "completion tokens consumed (0 if unknown)"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "required for every call after the first for this agent_id"
},
"amount_cents": {
"type": "integer",
"description": "spend amount in cents (100 = $1.00), 0-10000000"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "required when claiming a brand-new agent_id; not\n needed once the agent_id has been claimed"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Track Agent Spend",
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}| monthly_tokens | integer | monthly token-burn cap (0 = no cap) |
{
"name": "ledger_set_budget",
"title": "Set Agent Budget",
"description": "Set spending caps for an agent. Warns at 80%, blocks spend when exceeded\n— enforced: a ledger_track call that would cross the cap is rejected.\n\nDollar caps (monthly_cents/daily_cents) and token caps (monthly_tokens/\ndaily_tokens) are independent dimensions: dollar caps only cover\nnon-\"tokens\" rails, token caps only cover rail=\"tokens\" bookkeeping rows\n(tokens_in/tokens_out). Set both if the agent uses both.\n\nMonthly cap is required; the rest are optional (0 = no limit).\nOverwrites any existing budget for the agent — with one rule: raising\nor removing an existing cap requires the workspace_key. An agent_secret\ncan tighten its own caps but never loosen them; to grow an allowance\nthe agent asks its owner (see ledger_request_approval). Claiming a\nbrand-new agent_id requires your workspace_key; that first call mints an\nagent_secret (returned once — save it); later calls for that agent_id\nmust pass the agent_secret back (no workspace_key needed again).",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"monthly_cents"
],
"properties": {
"agent_id": {
"type": "string",
"description": "unique agent identifier"
},
"daily_cents": {
"type": "integer",
"default": 0,
"description": "daily spending cap in cents (0 = no daily cap)"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "required for every call after the first for this agent_id"
},
"daily_tokens": {
"type": "integer",
"default": 0,
"description": "daily token-burn cap (0 = no cap)"
},
"monthly_cents": {
"type": "integer",
"description": "monthly spending cap in cents"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "required when claiming a brand-new agent_id; not\n needed once the agent_id has been claimed"
},
"monthly_tokens": {
"type": "integer",
"default": 0,
"description": "monthly token-burn cap (0 = no cap)"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Set Agent Budget",
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}| string |
| durable name for this consumer (1-64 chars, [A-Za-z0-9._-]) |
| agent_secret | string | the agent's own secret (either this or workspace_key) |
| workspace_key | string | the owning workspace's key (either this or agent_secret) |
| client_started | string | when your process booted — paired with client_instance |
| client_instance | string | your process identity (e.g. pid or per-boot token) — enables restart redelivery |
{
"name": "ledger_wait_events",
"title": "Wait for Agent Events",
"description": "Long-poll an agent's event feed — how an agent with no public URL receives alerts.\n\nWebhooks (POST /v1/webhooks) push events to a URL you own; an agent on\nstdio MCP cannot host one, so it waits here instead. Call this in a loop:\nthe call holds open up to `timeout` seconds (max 30) and returns when\nevents arrive or the wait lapses.\n\n`consumer_id` names this consumer durably — pick a stable one\n(e.g. \"claude-code-main\") and reuse it. Each call returns a `cursor`;\npass it back on your next call once you have processed that batch — that\nis the ack. To get restart redelivery, also pass `client_instance` (your\nprocess id or any per-boot token) and `client_started` (when your\nprocess booted): when the pair changes, events that were served but\nnever acked come back with `redelivered: true`, so nothing is lost to a\ncrash between serve and process. (The stdio MCP server supplies its own\npid/started automatically — hosted callers must opt in because the\ngateway cannot see the client's process.)\n\nEach event is an envelope: id (deterministic — dedupe on it), kind\n(alert.raised | budget.warning | budget.exceeded | anomaly.detected),\nsummary, context (agent_id, alert_type, timestamp),\nalerts_since_last_write (how many alerts are stacked up since the\nagent's last spend write — use it to throttle escalation), redelivered.\n\nRequires a credential: either the agent's own agent_secret or its\nworkspace's workspace_key (same rule as GET\n/v1/agents/{agent_id}/events/wait).",
"inputSchema": {
"type": "object",
"required": [
"agent_id",
"consumer_id"
],
"properties": {
"name": {
"type": "string",
"default": "mcp",
"description": "optional label for this consumer instance"
},
"cursor": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "line offset you have processed through (omit to continue)"
},
"timeout": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "seconds to hold the call open (default 5, max 30)"
},
"agent_id": {
"type": "string",
"description": "unique agent identifier"
},
"consumer_id": {
"type": "string",
"description": "durable name for this consumer (1-64 chars, [A-Za-z0-9._-])"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (either this or workspace_key)"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key (either this or agent_secret)"
},
"client_started": {
"type": "string",
"default": "",
"description": "when your process booted — paired with client_instance"
},
"client_instance": {
"type": "string",
"default": "",
"description": "your process identity (e.g. pid or per-boot token) —\nenables restart redelivery"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Wait for Agent Events",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}{
"name": "ledger_check_spend",
"title": "Check Before Spending",
"description": "Ask BEFORE you spend: may this agent spend this much right now?\n\nReturns allowed (true/false), a stable reason code (within_budget,\nover_monthly_cap, over_daily_cap, over_monthly_token_cap,\nover_daily_token_cap, no_budget_set, unpriced_model), a one-line message,\nthe cost estimate, the price used (with its source and as_of date) and\nevery budget window with cap, spent and remaining.\n\nSame decision the /proxy/{provider} gate enforces. Read-only: nothing is\nrecorded or reserved, so record the spend with ledger_track afterwards.\n\nGive exactly one spend shape: amount_cents (any rail, e.g. an x402\npurchase), OR model with tokens_in/tokens_out.",
"inputSchema": {
"type": "object",
"required": [
"agent_id"
],
"properties": {
"model": {
"type": "string",
"default": "",
"description": "model id to price from tokens (instead of amount_cents)"
},
"agent_id": {
"type": "string",
"description": "the agent that would spend"
},
"tokens_in": {
"type": "integer",
"default": 0,
"description": "expected input tokens (with model)"
},
"tokens_out": {
"type": "integer",
"default": 0,
"description": "expected output tokens, e.g. your max_tokens (with model)"
},
"agent_secret": {
"type": "string",
"default": "",
"description": "the agent's own secret (either this or workspace_key)"
},
"amount_cents": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "the spend in cents, if you already know it"
},
"workspace_key": {
"type": "string",
"default": "",
"description": "the owning workspace's key (either this or agent_secret)"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"title": "Check Before Spending",
"readOnlyHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}