Budgets & Kill Switch

Agent work can be free, consumption-based, or passed through externally. That’s why you check wallet and budget rules before cost-relevant actions.

All gateway consumption and budget fields are specified in Credits. Payment or invoice fields may carry a currency such as EUR; that is then document or provider currency, not the consumption unit of the agent gateway.

Reading the wallet

After owner OTP claim and webRichtung activation, wallet.balance.get reads the current balance of the organization’s owner wallet. It is read-only and uses the scope billing.wallet:read.

Checking the budget

The capability wallet.agent_budget.guard.check checks whether a planned operation is within budget, cap, and kill switch limits. Use it before a paid target capability; repeat the check if intent, parameters, or cost estimate change.

Send the cost estimate from the target dry_run to the guard. estimated_cost.amount_max is a decimal string in the dry_run; for estimated_cost_credits you pass the same value as a JSON number:

{
  "id": "wallet.agent_budget.guard.check",
  "params": {
    "capability_id": "documents.document.upload",
    "estimated_cost_credits": 0.09,
    "window": "task"
  }
}

Field	Rule
capability_id	Required. Capability you want to execute afterward.
estimated_cost_credits	Required. Number in credits. Use dry_run.estimated_cost.amount_max; dry_run.estimated_cost.currency must be credits.
window	Optional. task, daily, or monthly; if you’re unsure, start with task.

The guard is executed via /mcp/invoke. The successful response uses the normal invoke envelope; the guard decision is under result:

{
  "interface_version": "1.0",
  "status": "succeeded",
  "capability_id": "wallet.agent_budget.guard.check",
  "resolved_version": "1.0.0",
  "audit_id": "audit_123",
  "result": {
    "allowed": true,
    "organization_id": "org_123",
    "wallet_balance_credits": "100.00",
    "estimated_cost_credits": 0.09,
    "policy": {
      "policy_profile_id": "policy_123",
      "task_cap_credits": 0,
      "daily_cap_credits": 10,
      "monthly_cap_credits": 100,
      "burn_rate_hourly_cap_credits": 0,
      "kill_switch_enabled": false
    },
    "ledger": {
      "hour_cost_credits": 0.2,
      "today_cost_credits": 0.5,
      "month_cost_credits": 2
    }
  }
}

All cap and ledger fields end with _credits. If status is not succeeded or result.allowed is not true, you do not execute the target capability.

Cap semantics: A cap field only limits when its numeric value is greater than 0. 0 means no active cap in this window. It is not a default value, not a lock, and not an unknown state. A response with result.allowed: true and individual cap values of 0 is therefore correct if wallet, other active caps, and kill_switch_enabled do not block.

Payload under result:

Field	Meaning
allowed	true if wallet, caps, and kill switch do not block the planned operation.
organization_id	Owner organization whose wallet and policy were checked.
wallet_balance_credits	Current balance of the owner wallet as a decimal string in credits.
estimated_cost_credits	Checked estimate as a number in credits.
policy.policy_profile_id	Active policy profile or null.
policy.task_cap_credits	Cap for this operation in credits; only values > 0 are active, 0 means no active cap.
policy.daily_cap_credits	Daily cap in credits; only values > 0 are active, 0 means no active cap.
policy.monthly_cap_credits	Monthly cap in credits; only values > 0 are active, 0 means no active cap.
policy.burn_rate_hourly_cap_credits	Hourly burn rate cap in credits; only values > 0 are active, 0 means no active cap.
policy.kill_switch_enabled	true stops new agent executions.
ledger.hour_cost_credits	Credits already counted in the current hourly window.
ledger.today_cost_credits	Credits already counted in the current daily window.
ledger.month_cost_credits	Credits already counted in the current monthly window.

Kill switch

A kill switch stops agent executions until an authorized person releases it again. Treat capability_disabled as a hard lock and do not attempt to circumvent it.

Practical workflow

1. Read describe of the target capability.
2. If describe.dry_run has the value required, first execute a successful dry_run with the same parameters.
3. For paid actions, execute a cost preflight and send dry_run.estimated_cost.amount_max as a JSON number to wallet.agent_budget.guard.check.
4. Only execute the target capability if status: "succeeded" and result.allowed: true.
5. In case of budget error: do not execute, but use handover or feedback instead.

Next

dry_run & cost preflight