AgentLedger — Per-Agent Spend Management
Track AI agent spend across x402/MPP/API-key rails, set budget caps, catch
spending anomalies, keep audit trails. The "Datadog for agent spending" —
the #1 verified community ask from agent builders.
🎯 Free tier: 3 agents per workspace, no card, no login. POST /start mints the workspace and shows the key once.
Connect AgentLedger
Connecting takes no auth handshake. Before your first write you need a
workspace_key, which you get one of two ways:
- Autonomous agent with a wallet:
POST /v1/billing/x402 with an
X-PAYMENT header. The paying wallet becomes the workspace identity —
no email, no login, no human in the loop.
- Human: open
/start — no
signup, no login, no card. The workspace_key is shown once, right there, and
the page carries the upgrade link for that workspace.
The key claims new agent_ids. Each claim mints that agent's own
agent_secret, which is what authenticates every later write — the
workspace_key is never needed again for that agent.
Claude Code:
claude mcp add --transport http agent-ledger https://aiagentscity.com/mcp/
Codex:
codex mcp add agent-ledger --url https://aiagentscity.com/mcp/
Cursor — merge into mcp.json:
{
"mcpServers": {
"agent-ledger": {
"url": "https://aiagentscity.com/mcp/"
}
}
}
Any other MCP client: point it at the streamable-http remote
https://aiagentscity.com/mcp/ — no headers,
no auth handshake required to connect.
Try these prompts once connected:
- "Track my Claude Code spend"
- "Alert when any agent exceeds $50/day"
- "Weekly P&L report"
Try it — get a key, then track
curl -X POST https://aiagentscity.com/v1/track \
-H "Content-Type: application/json" \
-H "AL-API-Version: 2026-09-01" \
-d '{"agent_id":"YOUR_AGENT_ID","rail":"x402","amount_cents":100,"service":"search_query","workspace_key":"YOUR_WORKSPACE_KEY"}'
curl -X POST https://aiagentscity.com/v1/budget \
-H "Content-Type: application/json" \
-H "AL-API-Version: 2026-09-01" \
-d '{"agent_id":"YOUR_AGENT_ID","monthly_cents":5000,"agent_secret":"YOUR_SAVED_SECRET"}'
curl https://aiagentscity.com/v1/report/YOUR_AGENT_ID \
-H "X-Agent-Secret: YOUR_SAVED_SECRET"
Want to just look at it? Every agent has a human-readable page (send the
secret as a header, no curl needed for the JSON):
https://aiagentscity.com/v1/report/YOUR_AGENT_ID/html
/v1/report, /v1/tokens, and /v1/alerts all require either
X-Agent-Secret: <agent's secret> or X-Workspace-Key: <the workspace's key>
— missing or wrong credential gets 401. Headers only: there is no cookie or
session arm, and no unauthenticated read path on REST or MCP. This is what
stops a stranger from reading or overwriting someone else's agent_id.
Note this is a deliberate break from AgentLedger's earlier "share the link,
anyone can read it" behavior — traded for real isolation between customers.
Two lines to a metered, capped agent
pip install "aiagentscity-ledger[wrapper]"
agent-ledger init --agent YOUR_AGENT_ID
from openai import OpenAI
import agentledger
client = agentledger.wrap(OpenAI(api_key=OPENAI_KEY),
agent_id="YOUR_AGENT_ID", agent_secret="<from .env>")
That is the whole integration. wrap() repoints the client's base URL at the proxy and
adds two identity headers — it does not patch or subclass the SDK, so streaming, tool
calls and retries behave exactly as before. Anthropic's client works identically. Your
provider key is forwarded untouched and never stored.
Not using a Python SDK? Point any OpenAI- or Anthropic-compatible client at
<base>/proxy/openai/v1/ (or /proxy/anthropic) with X-AL-Agent and X-AL-Secret.
Install (MCP clients)
{
"mcpServers": {
"agent-ledger": {
"url": "https://aiagentscity.com/mcp/"
}
}
}
Tools: ledger_track, ledger_set_budget, ledger_check_spend, ledger_report, ledger_alerts,
ledger_price, ledger_proxy_attach, ledger_api_docs, ledger_examples,
ledger_request_approval, ledger_approvals, ledger_approval_decide,
ledger_start, ledger_rotate_secret, ledger_revoke_secret.
Agent-facing API reference: llms.txt
Runnable code recipes: recipes.md
Features
- Multi-rail neutral — x402, MPP, API keys, manual entries; not locked to one payment rail
- Token→cost auto-pricing — send tokens + model and the dollar amount is computed for you;
an unpriced model is refused rather than silently recorded as free
- Budget enforcement — warns at 80% of cap, rejects the ledger write that would cross it
- Any provider, config not code —
providers.json lists the vendors the proxy can forward
to (OpenAI, Anthropic, DeepSeek and Moonshot ship as examples); adding one is a config edit
- Proxy enforcement (the real thing) — point your provider
base_url at /proxy/{provider}
and a call that would cross the cap is refused before the provider is contacted, so the money
is never spent. Pass-through: your provider key is forwarded, never stored
- Anomaly detection — spending-spike alerts per agent
- Alerts that arrive — push budget warnings (80%), real budget blocks, and
anomalies to an http(s) webhook you own; every delivery attempt is receipted,
failures included
- Audit trails — every entry persisted with rail, service, and timestamp
- Shareable report links —
POST /v1/report/{agent_id}/share mints a read-only,
expiring URL that opens in a plain browser (no header, no credential); revoke the
lot in one call
- Credential recovery — a lost
agent_secret never bricks an agent_id: the
workspace_key mints a replacement (POST /v1/agents/{agent_id}/rotate-secret) or
revokes it while keeping the spend history
- Per-workspace isolation — your agents, your cap, your subscription; nothing is shared across customers
- Free tier: 3 agents per workspace — the only paid path is the agent rail:
POST /v1/billing/x402 buys a renewable 24h Pro pass (unlimited agents on the
wallet's workspace) for $0.01 USDC. There is no human checkout or monthly plan.
Architecture
- Core engine (
ledger_engine.py): per-agent JSONL ledgers, budget state, alert log,
per-agent secret (ensure_agent_secret — a new claim requires a workspace_key,
and mints the agent's own agent_secret for every write after it)
- Identity (
identity.py): the single place a caller is resolved — agent_secret
or workspace_key, both header-borne. Every gate (claim, read, billing) calls
into it rather than rolling its own check.
- Workspaces (
workspace_engine.py): per-customer identity + plan state, keyed by
wallet address (x402, no human) or by nothing at all for a plain POST /start
workspace
- REST API (
api_server.py, FastAPI): app creation, meta endpoints, the human
start/buy pages and router includes; endpoints live in routes_agents.py and
routes_billing.py. Hosted streamable-http MCP at /mcp/
/v1/agents (full cross-tenant listing) is owner-only, requires X-Al-Admin header- Reads (
/v1/report, /v1/tokens, /v1/alerts) require X-Agent-Secret or
X-Workspace-Key; the MCP read tools take the same two credentials as
parameters, so neither surface has an unauthenticated read path
- Credential lifecycle:
POST /v1/agents/{agent_id}/rotate-secret and
/revoke-secret are workspace_key-only. An agent's own agent_secret
deliberately cannot rotate itself — if it could, a leaked agent credential
would permanently lock its real owner out. Revoke overwrites the stored
secret rather than deleting it, so the agent_id stays claimed and cannot be
picked up by another workspace
- Input validation: agent_id restricted to
[A-Za-z0-9._-]{1,64} (path-traversal safe),
rail whitelisted to mpp/x402/api_key/manual, amount + budget caps bounded [0, $100k]
- Stripe webhook is fail-closed: events are rejected unless the HMAC signature
verifies against
STRIPE_WEBHOOK_SECRET_AL. The human checkout endpoint is
retired (410) — the webhook remains wired only so subscriptions already in
flight when it was removed can still complete; a verified pro checkout marks
that workspace its paid tier via its client_reference_id.
entradox@icloud.com