Docs/Guides/Per-Agent Budgets

Per-Agent Budgets

Allocate credit budgets to individual agents or teams. Where budgets are enforced, SatGate refuses the call when a budget runs out: HTTP 402 on an HTTP route, JSON-RPC error -32000 on a paid MCP tool call. No one has to step in.

How budgets work

Every SatGate token can have a credit budget attached via delegation. Credits are abstract units — you define what 1 credit means (e.g., 1 credit = $0.01, or 1 credit = 1 API call).

Credit budgets are enforced on MCP tool calls only in Control mode. On HTTP, they are enforced on Control routes, on kind: pay routes, and on kind: capability routes that set a positive costCredits, a positive pay.price, pay.enforceBudget: true or a Control pay.mode. An Observe route never refuses a call because a token's budget ran out, whatever cost or budget settings it has. Where budgets are enforced, an HTTP request is rejected with HTTP 402 (Payment Required) once the budget is exhausted, and a paid MCP tool call gets JSON-RPC error -32000: "Budget exhausted" when nothing is left, or "Insufficient budget" when the call costs more than what is left.

Setting up budgets

  1. Define tool costs in the MCP Cost Profile. Assign a credit cost to each tool (e.g., echo: 1 credit, http_fetch: 10 credits).
  2. Create a delegation token on the Delegation & credit limits page. Set the credit limit, cost center, and department.
  3. Switch to Control mode in the MCP Cost Profile to start enforcing budgets.

Budget hierarchy

Budgets follow the delegation tree. On the Delegation & credit limits page, a parent token with 1,000 credits can delegate 500 credits to a child token: the 500 credits move from the parent's budget to the child's, leaving the parent 500. The child can delegate part of its budget to sub-agents the same way. Each token's spending comes out of its own budget.

Department (1,000 cr)
├── Team Lead (500 cr)
│   ├── Agent A (200 cr)  ← spends 50 → 150 remaining
│   └── Agent B (300 cr)
└── Auditor (500 cr, read-only)

What happens when budget runs out

Observe mode

Logged in Shadow Report. Agent continues.

Control

Budget enforced. The call is refused: HTTP 402 on an HTTP route, JSON-RPC error -32000 on a paid MCP tool call.

Related