Budgets & Metering

Grant budget fields

Budget limits live on individual grants inside a signed capability. Each grant targets one tool on one server and can carry any combination of max_cost_per_invocation, max_total_cost, and max_invocations. The YAML fragments below are scopes for issuance; issuance signs the capability that contains them.

MonetaryAmount carries exactly two fields, units and currency. Units are the currency's minor units, so 100 USD units is one dollar and the type never holds a float.

Three limits on one grant

Combine a cap per call, an aggregate cap, and a call count. The Python tab builds the same grant with the SDK's typed models (pip install chio-sdk).

grants:
  - server_id: models
    tool_name: complete
    operations: [invoke]
    max_cost_per_invocation:
      units: 100     # USD 1.00 per call
      currency: USD
    max_total_cost:
      units: 5000    # USD 50.00 in total
      currency: USD
    max_invocations: 500

from chio_sdk import ChioScope, MonetaryAmount, Operation, ToolGrant

scope = ChioScope(
    grants=[
        ToolGrant(
            server_id="models",
            tool_name="complete",
            operations=[Operation.invoke],
            max_cost_per_invocation=MonetaryAmount(units=100, currency="USD"),
            max_total_cost=MonetaryAmount(units=5000, currency="USD"),
            max_invocations=500,
        )
    ]
)

Serializing the model with exclude_none=True yields these grant fields; key order carries no meaning.

{
  "grants": [
    {
      "server_id": "models",
      "tool_name": "complete",
      "operations": [
        "invoke"
      ],
      "max_invocations": 500,
      "max_cost_per_invocation": {
        "units": 100,
        "currency": "USD"
      },
      "max_total_cost": {
        "units": 5000,
        "currency": "USD"
      }
    }
  ]
}

Call count only

A free tool can still be bounded: max_invocations stops a runaway loop with no monetary accounting.

grants:
  - server_id: web
    tool_name: search
    operations: [invoke]
    max_invocations: 100
    # No monetary limits: the tool is free

Aggregate cap only

The schema accepts a total by itself. Monetary admission reserves max_cost_per_invocation and defaults it to zero when absent, and the local-ledger adapter refuses a zero-value authorization, so pair a total with an explicit per-call ceiling when you run the example.

grants:
  - server_id: models
    tool_name: complete
    operations: [invoke]
    max_total_cost:
      units: 5000    # USD 50.00
      currency: USD

Per-call and total caps

For a tool whose cost varies per call, the per-call cap keeps one expensive call from consuming the whole budget and the total cap bounds aggregate spend.

grants:
  - server_id: models
    tool_name: complete
    operations: [invoke]
    max_cost_per_invocation:
      units: 200       # USD 2.00 per call
      currency: USD
    max_total_cost:
      units: 10000     # USD 100.00 in total
      currency: USD

Several grants in one capability

One capability can hold several grants, each with its own budget, so an agent can reach several tools with different spending profiles.

grants:
  - server_id: models
    tool_name: complete
    operations: [invoke]
    max_cost_per_invocation:
      units: 100
      currency: USD
    max_total_cost:
      units: 5000
      currency: USD
    max_invocations: 500

  - server_id: web
    tool_name: search
    operations: [invoke]
    max_invocations: 200
    # Free tool, no monetary limits

  - server_id: pricing
    tool_name: publish_price
    operations: [invoke]
    max_cost_per_invocation:
      units: 10      # USD 0.10 per published price
      currency: USD
    max_total_cost:
      units: 500     # USD 5.00 in total
      currency: USD

Delegated budgets

A parent narrows a child's total and per-call limits with ReduceTotalCost and ReduceCostPerInvocation, and its call count with ReduceBudget. Parent-child accounting comes from the signed delegation chain and its budget authority; two independently issued tokens hold two separate budgets.

# Parent token: USD 100.00 in total
grants:
  - server_id: models
    tool_name: complete
    operations: [invoke]
    max_total_cost:
      units: 10000     # USD 100.00
      currency: USD
    max_invocations: 1000

# Child token, attenuated from the parent: USD 10.00
# Created with ReduceTotalCost and ReduceBudget
# (optionally ReduceCostPerInvocation)
grants:
  - server_id: models
    tool_name: complete
    operations: [invoke]
    max_total_cost:
      units: 1000      # USD 10.00, reduced from the parent's USD 100.00
      currency: USD
    max_invocations: 100  # reduced from the parent's 1000

To attribute delegated spend, trace the delegation chain and the budget-authority records. delegation_depth records the chain depth used for the call, and root_budget_holder is populated from the capability issuer. Siblings can also share one family monetary cap, with basis-point shares bounding each child's draw; see shared capacity.

Tool pricing helpers

A tool server declares its price with the NativeTool helpers. per_invocation_price sets the billing unit to "invocation"; flat_price sets one price with no billing unit; per_unit_price prices a custom unit; hybrid_price adds a usage price to a base. The helpers describe a pricing contract. The service measures usage and reports the cost.

NativeTool::new("quote", "Quote a SKU", schema.clone())
    .per_invocation_price(1, "USD"); // USD 0.01 per quote
NativeTool::new("read_order", "Read one order", schema.clone())
    .flat_price(500, "USD"); // USD 5.00 per call
NativeTool::new("complete", "Run a model completion", schema.clone())
    .per_unit_price(2, "USD", "1k_tokens"); // USD 0.02 per 1,000 tokens
NativeTool::new("search", "Search competitor prices", schema)
    .hybrid_price(25, 10, "USD", "result"); // USD 0.25 plus 0.10 per result

The host authenticates the manifest before registration. A connection reports its realized charge as a ToolInvocationCost. The default invoke_with_cost returns no amount, and the kernel then debits the authorized ceiling as a conservative charge. The service connection reports explicitly:

Some(ToolInvocationCost {
    units: PRICE_UNITS,
    currency: "USD".into(),
    breakdown: Some(json!({"fixed_service_charge": PRICE_UNITS})),
})

Publishing offers and planning a budget from a quote are in Tool Pricing.

Financial receipt metadata

The monetary path records its decision as FinancialReceiptMetadata in metadata.financial. Depending on the outcome, the block holds:

• grant_index: the grant inside the capability that paid for the call.
• cost_charged and currency: the recorded amount, read with the settlement status and the rail.
• budget_remaining and budget_total: a balance snapshot and the grant's original total.
• delegation_depth and root_budget_holder: the chain depth and the issuing capability key as bare lowercase hex.
• payment_reference: an optional reference that joins the receipt to an external settlement system.
• settlement_status: whether the charge is pending, settled, failed, or not applicable.
• cost_breakdown: optional reporting and payment details, not necessarily an additive cost list.
• oracle_evidence: the conversion record for a cross-currency charge.
• attempted_cost: the requested exposure on a monetary refusal.

A receipt without the block makes no statement about price. Invocation-only quotas can refuse with no financial block at all.

Query receipts with financial data

Local reads against a --receipt-db path fail closed without a tenant scope: pass --tenant <id>, or --admin-all for an explicit cross-tenant operator read, on every local query. --min-cost and --max-cost both require --cost-currency.

# Receipts with cost information for one tool
chio --receipt-db ./receipts.sqlite receipt list --tenant team-a \
    --tool-server models --tool-name complete

# Expensive calls, by minimum cost in minor units
chio --receipt-db ./receipts.sqlite receipt list --tenant team-a \
    --min-cost 100 --cost-currency USD --tool-server models

# Failed settlements in the returned page
chio --receipt-db ./receipts.sqlite receipt list --tenant team-a \
    --tool-server models \
    | jq 'select(.metadata.financial.settlement_status == "failed")'

# Monetary refusals in the returned page
chio --receipt-db ./receipts.sqlite receipt list --tenant team-a --outcome deny \
    | jq 'select(.metadata.financial.attempted_cost != null)'

# One receipt by ID; follow next_cursor for records beyond this page
chio --receipt-db ./receipts.sqlite receipt list --tenant team-a --limit 500 \
    | jq 'select(.id == "d1b874355e0cf8b2d5aea4d5b6bc0c71e231420654798bddf84d20cbd44409d3")'

budget_total minus budget_remaining is cumulative committed usage; a single invocation's reservation is in its budget-authority events. One response is one page of the log: for a shared store, follow the cursor loop in Query & Audit Receipts before you aggregate, and export to a SIEM for continuous dashboards (SIEM export).

Live budget state

The chio mcp serve-http admin router serves a read-only GET /admin/budgets?capability_id=<id>&limit=<n>, gated by --admin-token (environment variable CHIO_ADMIN_TOKEN). It lists the current per-grant invocation counts for one capability.

Budget-authority events

The hold-and-reconcile lifecycle is recorded in metadata.budget_authority: the authorization event, the invocation capture, and a terminal disposition. This capture comes from a simulated prepaid call; the events describe budget accounting, and the rail records settlement separately.

$ jq '.metadata.budget_authority | {authority_profile, guarantee_level, metering_profile, authorize, terminal}' ./bundle.json

{
  "authority_profile": "authoritative_hold_event",
  "guarantee_level": "single_node_atomic",
  "metering_profile": "max_cost_preauthorize_then_reconcile_actual",
  "authorize": {
    "budget_commit_index": 1,
    "committed_cost_units_after": 100,
    "event_id": "budget-hold:governed-sim-req-1:cap-01a07037-33c8-7d20-a83c-a4a5a131a3d4:0:authorize",
    "exposure_units": 100
  },
  "terminal": {
    "budget_commit_index": 3,
    "committed_cost_units_after": 100,
    "disposition": "reconciled",
    "event_id": "budget-hold:governed-sim-req-1:cap-01a07037-33c8-7d20-a83c-a4a5a131a3d4:0:reconcile",
    "exposure_units": 100,
    "realized_spend_units": 100
  }
}

Failed settlement records

On the non-durable reconciliation path, a report above the authorization produces a failed financial record. settlement_status is failed; cost_charged holds the reported cost, because recorded_cost is set to actual_cost; and the budget is debited no further than the reservation. In this illustration a 100-unit reservation meets a 220-unit report.

{
  "grant_index": 0,
  "cost_charged": 220,
  "currency": "USD",
  "budget_remaining": 900,
  "budget_total": 1000,
  "settlement_status": "failed",
  "cost_breakdown": {
    "compute": 180,
    "io": 40
  }
}

A failed status records that 220 units were reported, not that they were paid, and a rail failure produces the same status. Inspect the operation's error and payment state before attributing it to the tool.

Cross-currency configuration

When a grant's currency differs from a tool's pricing currency, the kernel resolves the rate through chio-link, a pinned Chainlink and Pyth oracle runtime. Build a PriceOracleConfig in Rust, usually with PriceOracleConfig::base_arbitrum_default(base_rpc, arbitrum_rpc), and hand it to the kernel with set_price_oracle. The struct is deny_unknown_fields with no defaulted fields: a chain inventory (operator.chains), an operator policy block, a typed egress_contract that gates every outbound oracle request fail-closed, and one Chainlink feed address per pair with an optional Pyth fallback and a per-pair policy.

Replace the base-mainnet.example endpoint and its matching egress authority with your RPC before validation. The feed addresses are source defaults.

{
  "primary": "chainlink",
  "fallback": "pyth",
  "refresh_interval_seconds": 60,
  "pyth": {
    "hermes_url": "https://hermes.pyth.network"
  },
  "operator": {
    "global_pause": false,
    "chains": [
      {
        "chain_id": 8453,
        "label": "base-mainnet",
        "caip2": "eip155:8453",
        "rpc_endpoint": "https://base-mainnet.example",
        "enabled": true,
        "sequencer_uptime_feed": "0xBCF85224fc0756B9Fa45aA7892530B47e10b6433",
        "sequencer_grace_period_seconds": 300
      }
    ],
    "pair_overrides": [],
    "monitoring": {
      "alert_on_fallback": true,
      "alert_on_degraded": true,
      "alert_on_pause": true,
      "alert_on_sequencer": true
    }
  },
  "egress_contract": {
    "tenant_egress_namespace": "chio-link",
    "allowed_schemes": ["https"],
    "allowed_authority_set": ["hermes.pyth.network", "base-mainnet.example"],
    "deny_loopback": true,
    "deny_link_local": true,
    "deny_ipv6_ula": true,
    "max_redirect_chain": 1,
    "max_response_bytes": 4194304
  },
  "pairs": [
    {
      "base": "USDC",
      "quote": "USD",
      "chain_id": 8453,
      "chainlink": {
        "address": "0x7e860098F58bBFC8648a4311b374B1D669a2bc6B",
        "decimals": 8,
        "heartbeat_seconds": 68400
      },
      "pyth": {
        "id": "0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a"
      },
      "policy": {
        "max_age_seconds": 600,
        "divergence_threshold_bps": 500,
        "exchange_rate_margin_bps": 200,
        "twap_enabled": false,
        "twap_window_seconds": 600,
        "twap_max_observations": 10,
        "stable_pair": true,
        "degraded_mode": {
          "enabled": false,
          "max_stale_age_seconds": 300,
          "extra_margin_bps": 800
        }
      }
    },
    {
      "base": "ETH",
      "quote": "USD",
      "chain_id": 8453,
      "chainlink": {
        "address": "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70",
        "decimals": 8,
        "heartbeat_seconds": 300
      },
      "pyth": {
        "id": "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace"
      },
      "policy": {
        "max_age_seconds": 600,
        "divergence_threshold_bps": 500,
        "exchange_rate_margin_bps": 200,
        "twap_enabled": true,
        "twap_window_seconds": 600,
        "twap_max_observations": 10,
        "stable_pair": false,
        "degraded_mode": {
          "enabled": false,
          "max_stale_age_seconds": 300,
          "extra_margin_bps": 800
        }
      }
    }
  ]
}

exchange_rate_margin_bps adds a conservative buffer to the converted rate; one basis point is 0.01%. divergence_threshold_bps trips a circuit breaker when Chainlink and Pyth disagree beyond the threshold, and max_age_seconds bounds how stale a cached rate may be before resolution fails closed. twap_enabled, twap_window_seconds, and twap_max_observations govern time-weighted averaging; stable_pair marks a pegged pair; degraded_mode bounds how far resolution relaxes its staleness and margin ceilings when a feed goes stale.

A successful conversion adds OracleConversionEvidence; a refusal before conversion carries none. source names the backend that produced the rate, authority names the receipt-side FX authority model, and the signed rate is the exact ratio rate_numerator / rate_denominator. Margin is a resolution input, never a field on the evidence. A pinned oracle signer adds oracle_public_key and signature.

{
  "metadata": {
    "financial": {
      "grant_index": 0,
      "cost_charged": 150,
      "currency": "USD",
      "budget_remaining": 850,
      "budget_total": 1000,
      "settlement_status": "pending",
      "oracle_evidence": {
        "schema": "chio.oracle-conversion-evidence.v1",
        "base": "USDC",
        "quote": "USD",
        "authority": "chio_link_runtime_v1",
        "rate_numerator": 100,
        "rate_denominator": 100,
        "source": "chainlink",
        "feed_address": "0x7e860098F58bBFC8648a4311b374B1D669a2bc6B",
        "updated_at": 1710000090,
        "max_age_seconds": 600,
        "cache_age_seconds": 12,
        "original_cost_units": 1500000,
        "original_currency": "USDC",
        "converted_cost_units": 150,
        "grant_currency": "USD"
      }
    }
  }
}

Other budget models

The grant ceiling above is enforced in try_charge_cost() against the durable hold ledger. chio-metering ships two helpers that evaluate budgets independently of that ceiling. Neither signs a kernel receipt or installs itself in the admission path.

Flat enforcer

budget::BudgetEnforcer applies a flat BudgetPolicy scoped to total, per-session, per-agent, and per-tool spend. A charge that breaches any scope returns a BudgetViolation naming the dimension. Its counters are process-local, reset on restart, and need external synchronization; durable spend belongs on the kernel hold ledger.

Budget hierarchy

budget_hierarchy::BudgetTree caps a draft spend at every ancestor BudgetNode across four dimensions: spend, tokens, requests, and warehouse bytes. A denying BudgetDecision reports the offending scope closest to the root through BudgetDenyReason. It suits organization, team, and project hierarchies where no child may exceed an ancestor. BudgetTree evaluates a supplied SpendSnapshot; the caller owns that snapshot's freshness, persistence, and atomic update with the work it authorizes.