Sessions and limits
Per-agent spend ceilings and failure budgets.
A session is a spending envelope for one agent — an amount ceiling, an optional warrant count, a failure budget and an expiry — checked before a warrant is allowed to open.
{
"agent_id": "agt_01J8Z3M4YQ7K2V9X",
"amount_ceiling": "50000000",
"amount_spent": "8400000",
"warrant_limit": 20,
"warrant_count": 3,
"failure_budget": 3,
"failure_count": 0,
"expires_at": "2026-08-16T12:00:00.000Z"
}Not the session that signs you in
This is a spend session belonging to an agent. The session that authenticates a person is a different thing entirely — an httpOnly cookie, described in Authentication. They share a word and nothing else.
Four limits, checked before anything opens
| Limit | Refused with | Meaning |
|---|---|---|
amount_ceiling | session_ceiling_exceeded | Total across the session, not per warrant. |
warrant_limit | session_warrant_limit_reached | Optional. Null means no count limit. |
failure_budget | session_failure_budget_spent | Consecutive failures tolerated. |
expires_at | session_expired | Wall-clock end of the envelope. |
A revoked session is refused with session_revoked.
All of these are 403, not 401. The caller is authenticated — their API key is fine — and the answer is still no. Re-authenticating would change nothing, which is exactly what a 403 tells a client.
The ceiling is cumulative
amount_spent accumulates across the session; it is not a per-warrant cap. A
session with a ceiling of 50000000 and 48000000 already spent will refuse a
warrant for 8400000, and the error reports all three figures so the agent can
tell how close it was rather than guessing.
Both counters increment in the same statement that opens the warrant, so two concurrent opens cannot both squeeze under the same remaining headroom.
The failure budget is the interesting one
failure_count counts consecutive failures. A clean settlement resets it to
zero.
When the budget is spent, two things happen and they are different in scope:
- The session is revoked. It opens nothing further.
- The agent's own failure count also advances, and when its budget is
spent the agent's status moves to
paused.
So a run of failures ends the current envelope, and a pattern of failures across envelopes stops the agent. The distinction matters because an agent that has found a broken supplier and is retrying it should stop after a few attempts, not after a few hundred.
Nothing here is a punishment for a single bad check. It is a circuit breaker, and the thing it protects against is an autonomous system spending real money in a loop nobody is watching.
Amounts
amount_ceiling and amount_spent are integer strings of the asset's smallest
unit, validated against ^[0-9]+$.
"50000000" 50.00 USDC
50000000 rejected — a JSON number
"50.00" rejected — not the smallest unitThey are stored as 64-bit integers and only ever compared as integers. A ceiling you can drift past through floating-point rounding is not a ceiling.