io.github.entradox/agent-ledger

Tools

• ledger_alerts

  Alert history for an agent: budget warnings (80% threshold) and spending spikes.

  shallow
• ledger_api_docs

  Self-serve documentation for AgentLedger — quickstart, MCP tools, REST endpoints, budget caps, error codes, and idempotency usage, as markdown.

  shallow
• 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 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.

  shallow
• ledger_examples

  Complete, runnable Python recipe for a common AgentLedger integration pattern.

  shallow
• ledger_list_agents

  Owner-only: full cross-tenant listing of every agent ever claimed on this instance, with totals. Requires the operator's admin_secret — this is a portfolio-wide view, not a per-agent report (use ledger_report for that, which needs no secret).

  shallow
• 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) / 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.

  shallow
• 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 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.

  shallow
• 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.

  shallow
• 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", "revoked": True, "_note"}, or {"error", "error_code"}.

  shallow
• 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 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"}.

  shallow
• 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 uses both. Monthly cap is required; the rest are optional (0 = no limit). Overwrites any existing budget for the agent. No signup: the first call for a new agent_id mints an agent_secret (returned once — save it); later calls for that agent_id must pass it back.

  shallow
• 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 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 (unlimited agents).

  shallow
• ledger_track

  Record a spend entry for an AI agent on any payment rail, with optional token counts. No signup: the first call for a new agent_id mints an agent_secret and returns it in the response — save it, every later call for that same agent_id must pass it back 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. Include tokens_in/tokens_out + model on every LLM call so token burn shows up in the /v1/tokens report.

  shallow
• read_skill

  Read a product skill file by its skill:// URI.

  shallow
• 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`.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/dbabc350-9627-4758-8f90-cb37d06bee9e/badge.svg)](https://vouch.tools/servers/dbabc350-9627-4758-8f90-cb37d06bee9e)