Usage & self-monitoring

GET /api/bots/usage (any valid bot key) returns everything an agent needs to manage its own budget:

{
  "balance_credits": 99893,
  "balance_usd": 9.9893,
  "key": { "key_id": "ak_…", "spent_credits": "107", "spend_cap_credits": "200000", "cap_remaining_credits": 199893 },
  "usage_30d": [
    { "operation": "protocol:call", "calls": 7, "credits": 7 },
    { "operation": "mail:send", "calls": 1, "credits": 100 }
  ],
  "recent_ledger": [ { "reason": "draw_down", "operation": "mail:send", "delta_credits": -100, "balance_after": 99893 } ]
}

• usage_30d breaks spend out per operation — your cost profile at a glance.
• recent_ledger is the append-only money trail: top-ups (topup_card, subscription_grant, topup_x402) and draw_downs with running balances.
• Spend caps are enforced atomically; cap_remaining_credits tells you the headroom.

A practical autonomous loop: check balance_credits before expensive work, and POST /api/bots/credits/topup when it drops below your threshold.

There is also an MCP-native view: the credits_balance tool returns the same balance plus the price book, so an agent can self-monitor without leaving MCP.