AgentLedger
Meter, cap, and block AI agent spend before the provider is charged.
| Endpoint | https://aiagentscity.com/mcp/ (streamable-http) |
|---|---|
| Registry version | 0.4.7 |
| Now | 18 tools · grade C (66) · pin ts_d8d95ac3e361243c38707455bf0f04bc · protocol 2025-06-18 |
| First / last listed | 2026-10-30 03:09 UTC / 2026-10-30 03:09 UTC |
| Grade over time | 2026-10-30: C (66), 18 tools |
Is this your server? Own a server? ToolFit hosted watch re-checks it every 24 h ($0.25 per 30 days) or 6 h ($0.60) and sends you an HMAC-signed webhook when its tools or grade change: POST https://api.youraitools.co/toolfit/v1/watch. To opt out, see About & opt-out.
Tools: ledger_rotate_secret ledger_revoke_secret ledger_track ledger_set_budget ledger_report ledger_proxy_attach ledger_alerts ledger_wait_events ledger_check_spend ledger_request_approval ledger_approvals ledger_approval_decide ledger_price ledger_start ledger_api_docs ledger_examples skills_list_tool read_skill
ledger_rotate_secret | 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 params: agent_id*, workspace_key* |
ledger_revoke_secret | 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", "re params: agent_id*, workspace_key* |
ledger_track | 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 t params: agent_id*, rail*, amount_cents*, service*, tokens_in, tokens_out, model, agent_secret, workspace_key |
ledger_set_budget | 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 params: agent_id*, monthly_cents*, daily_cents, monthly_tokens, daily_tokens, agent_secret, workspace_key |
ledger_report | 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). params: agent_id*, days, agent_secret, workspace_key |
ledger_proxy_attach | 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 se params: agent_id*, provider, agent_secret, workspace_key |
ledger_alerts | 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). params: agent_id*, agent_secret, workspace_key |
ledger_wait_events | 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 params: agent_id*, consumer_id*, agent_secret, workspace_key, cursor, timeout, client_instance, client_started, name |
ledger_check_spend | 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 params: agent_id*, amount_cents, model, tokens_in, tokens_out, agent_secret, workspace_key |
ledger_request_approval | 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 — t params: agent_id*, amount_cents*, service*, reason, agent_secret, workspace_key |
ledger_approvals | List spend-approval permits — yours, or your whole workspace's. params: agent_id, workspace_key, agent_secret, state |
ledger_approval_decide | 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 params: agent_id*, approval_id*, decision*, workspace_key* |
ledger_price | 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) params: model*, tokens_in, tokens_out |
ledger_start | 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 o params: none |
ledger_api_docs | Self-serve documentation for AgentLedger — quickstart, MCP tools, REST
endpoints, budget caps, error codes, and idempotency usage, as markdown. params: topic |
ledger_examples | Complete, runnable Python recipe for a common AgentLedger integration
pattern. params: pattern* |
skills_list_tool | 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`. params: none |
read_skill | Read a product skill file by its skill:// URI. params: uri* |
Entries describe changes in tool definitions. They are not statements about a server, its quality or its author. The grade measures how the tool definitions fit model providers (token cost, schema compatibility, confusable names) as scored by the ToolFit engine at the time of the listing. JSON: append .json. Opt-out: how or hello@youraitools.co.