AgentLedger

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

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string"
    },
    "workspace_key": {
      "type": "string"
    }
  },
  "required": [
    "agent_id",
    "workspace_key"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": 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"}.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string"
    },
    "workspace_key": {
      "type": "string"
    }
  },
  "required": [
    "agent_id",
    "workspace_key"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": 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. Include tokens_in/tokens_out + model on every LLM call so token burn shows up in the /v1/tokens report.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "unique agent identifier (e.g. \"research-agent-v2\")"
    },
    "rail": {
      "type": "string",
      "description": "payment rail used — one of \"mpp\", \"x402\", \"api_key\", \"manual\""
    },
    "amount_cents": {
      "type": "integer",
      "description": "spend amount in cents (100 = $1.00), 0-10000000"
    },
    "service": {
      "type": "string",
      "description": "what was purchased (e.g. \"search_query\", \"data_export\")"
    },
    "tokens_in": {
      "default": 0,
      "type": "integer",
      "description": "prompt tokens consumed (0 if unknown)"
    },
    "tokens_out": {
      "default": 0,
      "type": "integer",
      "description": "completion tokens consumed (0 if unknown)"
    },
    "model": {
      "default": "",
      "type": "string",
      "description": "model name (e.g. \"gpt-4o\") — token burn is reported per model"
    },
    "agent_secret": {
      "default": "",
      "type": "string",
      "description": "required for every call after the first for this agent_id"
    },
    "workspace_key": {
      "default": "",
      "type": "string",
      "description": "required when claiming a brand-new agent_id; not\n           needed once the agent_id has been claimed"
    }
  },
  "required": [
    "agent_id",
    "rail",
    "amount_cents",
    "service"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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. 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).

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "unique agent identifier"
    },
    "monthly_cents": {
      "type": "integer",
      "description": "monthly spending cap in cents"
    },
    "daily_cents": {
      "default": 0,
      "type": "integer",
      "description": "daily spending cap in cents (0 = no daily cap)"
    },
    "monthly_tokens": {
      "default": 0,
      "type": "integer",
      "description": "monthly token-burn cap (0 = no cap)"
    },
    "daily_tokens": {
      "default": 0,
      "type": "integer",
      "description": "daily token-burn cap (0 = no cap)"
    },
    "agent_secret": {
      "default": "",
      "type": "string",
      "description": "required for every call after the first for this agent_id"
    },
    "workspace_key": {
      "default": "",
      "type": "string",
      "description": "required when claiming a brand-new agent_id; not\n           needed once the agent_id has been claimed"
    }
  },
  "required": [
    "agent_id",
    "monthly_cents"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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).

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "unique agent identifier"
    },
    "days": {
      "default": 30,
      "type": "integer",
      "description": "report window in days (default 30)"
    },
    "agent_secret": {
      "default": "",
      "type": "string",
      "description": "the agent's own secret (either this or workspace_key)"
    },
    "workspace_key": {
      "default": "",
      "type": "string",
      "description": "the owning workspace's key (either this or agent_secret)"
    }
  },
  "required": [
    "agent_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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).

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "unique agent identifier"
    },
    "agent_secret": {
      "default": "",
      "type": "string",
      "description": "the agent's own secret (either this or workspace_key)"
    },
    "workspace_key": {
      "default": "",
      "type": "string",
      "description": "the owning workspace's key (either this or agent_secret)"
    }
  },
  "required": [
    "agent_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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 — it requires that agent's agent_secret or its workspace_key).

{
  "type": "object",
  "properties": {
    "admin_secret": {
      "default": "",
      "type": "string",
      "description": "operator admin secret (not the same as an agent_secret)"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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).

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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

{
  "type": "object",
  "properties": {
    "topic": {
      "default": "",
      "type": "string",
      "description": "\"quickstart\" | \"mcp\" | \"rest\" | \"budget\" | \"errors\" | \"idempotency\" | \"all\"\n   (default \"\" == \"all\"). Unknown topics fall back to the full docs."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "description": "\"python_tracking\" | \"budget_enforcement\" | \"weekly_report\" |\n     \"retry_safe_writes\""
    }
  },
  "required": [
    "pattern"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

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

{
  "type": "object",
  "properties": {
    "uri": {
      "type": "string",
      "description": "e.g. skill://<product>/<skill-name>/SKILL.md\n Get valid URIs from `skills_list_tool`."
    }
  },
  "required": [
    "uri"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}