A mandate is a spending policy attached to a specific agent. It answers the question every seller needs answered before accepting a payment: is this agent authorized to pay for this resource right now, and within what limits? Every payment Mandate approves is evaluated against a mandate — no mandate means no payment. You can create multiple mandates for the same agent to scope permissions by purpose, time period, or merchant.
Mandate fields
Mandate statuses
active — the mandate is valid and the policy engine will evaluate payments against it.revoked — manually disabled. The policy engine returns reason_code: "mandate_expired" for any payment that references a revoked mandate.exhausted — spent_total has reached max_spend_total. The database transitions the mandate to this status automatically when the final payment is charged. The policy engine treats exhausted mandates the same as expired ones.
Creating a mandate
Response (201 Created):
Revoking a mandate
No request body is required. The response returns the updated mandate object with status: "revoked".
Revoking a mandate takes effect immediately. Any ongoing agent activity that relies on this mandate will be blocked at the next policy evaluation. If the agent has already received a payment proof but has not yet presented it to the seller, the seller’s call to POST /v1/payments/verify will still succeed — verification does not re-run policy checks. Revoke with care when agent activity is in progress.
Important design notes
allowed_categories: [] means all categories are allowed — not zero.An empty allowed_categories array is a wildcard: the policy engine skips the category check entirely if the array is empty. To restrict an agent to specific categories, you must explicitly list them (e.g., ["data", "compute"]). This behavior is intentional — a mandate with no category list is a general-purpose mandate.
One mandate per purpose
A mandate belongs to exactly one agent and cannot be transferred. For agents that need to access multiple sellers for unrelated purposes — for example, one mandate for market data and another for compute — create separate mandates. This keeps your audit trail clean and lets you revoke one capability without affecting the other.
Budget is lifetime, not rolling
max_spend_total is a lifetime cap tracked by spent_total. There is no automatic reset. Once a mandate is exhausted, you must create a new mandate to continue authorizing payments for that agent. 
