Trust Layer

Cap kit spend. Gate external calls. Keep humans in the loop.

Configure per agent via PATCH /agents/:id/spend-policy. Stored on the agent as metadata.spendPolicy. Evaluated before every paid kit tool runs — before x402 payment is requested or verified.

Per-agent fields

Global operator controls

• Covered — kit-priced MCP tools

  Today: get_token_price ($0.001 per call). Any tool with a fixed price in its descriptor goes through: evaluate budget → payment required → verify → execute → settle → ledger entry.

• Not covered — variable third-party APIs

  paid_fetch uses whatever price the external x402 resource demands. Spend policy does not cap those amounts. Use Discovery Layer filters (maxUsdPrice, network, asset) and your own app rules before the agent calls paid_fetch.

• Not covered — on-chain transfers

  transfer builds unsigned transactions only. The kit does not sign, broadcast, or enforce recipient allowlists or transfer spend limits. Response includes policy.allowlistEnforced: false — custody and approval stay in the wallet or your signing service.

The kit does not replace your approval UI — it creates natural pause points.

• Unsigned transfers

  transfer

  transfer returns intent, unsigned transaction, and preflight suggestions. Nothing hits chain until your user or signing service approves — perfect for review amount and recipient flows in mobile or dashboard.

• Payment required

  payment required

  Paid kit tools and paid_fetch first return payment requirements. The host must obtain a signature (wallet, smart account, or delegated signer) before retrying with paymentPayload. Insert confirmation modals, step-up auth, or parent approval between probe and pay.

• Spend denial

  spend denied

  When budget is exceeded, the agent receives a clear denial — not a silent failure. Surface remaining budget in your UI and offer request higher limit or human override workflows outside MCP.

• Advisory mode

  dry-run

  Roll out policies in observe-only mode: SPEND_POLICY_DRY_RUN=true globally or hardBlock: false per agent. Log violations, alert operators, train models — then flip to hard block when ready.

1. 1

   Enable globally

   Set SPEND_POLICY_ENABLED=true in your deployment.

2. 2

   Set per-agent budget

   PATCH /agents/:id/spend-policy with enabled, budgetUsd, period, and optional hardBlock.

3. 3

   Agent calls a paid kit tool

   On tools/call (e.g. get_token_price), the router: (1) loads metadata.spendPolicy for the session agent, (2) sums agent_spend_ledger for the current daily or monthly UTC window, (3) compares projected spend (spent + tool price) to budgetUsd, (4) denies the request or continues to x402 payment flow.

4. 4

   After successful settlement

   Ledger records the spend in agent_spend_ledger (tool name, amount, request key, settled timestamp). Duplicate request keys are skipped idempotently. Remaining budget updates for the next call in the same period.

• Deny with data, not mystery

  Policy failures return machine-readable limits and remaining budget so agents and UIs can explain why and recover gracefully.

• Enforce where price is known

  Fixed kit tool prices are enforceable pre-payment. Variable third-party prices are steered via discovery and app policy — not guessed in the router.

• Custody stays out of the kit

  No signing keys in the service. Trust for transfers and large payments is composable: kit prepares, you approve and sign.

• Operator + per-agent knobs

  Global flag for rollout; per-agent budgets for tenant/customer segmentation; dry-run and advisory hardBlock for safe adoption.

• Idempotent ledger

  requestKey deduplication prevents double-counting when clients retry payments.

• Agent Interface

  Policy runs inside tools/call — same MCP session as balance and discovery. Payment Required and Spend Policy Denied errors are first-class JSON-RPC responses for hosts to handle.

• Identity Layer

  On-chain ERC-8004 identity proves who the agent is; spend policy limits what that agent can spend through kit-priced tools in a period.

• Discovery Layer

  maxUsdPrice and payTo filters are the trust front-door for external APIs. paid_fetch host allowlist is the trust back-door for which hosts may be called.

• Payments Layer

  x402 verify/settle happens after spend policy passes (for kit tools). Ledger ties policy to actual settled micropayments, not estimates.

• Trust Layer

  You are here

  Cap kit tool spend, gate external calls with allowlists, keep humans in the loop for value that moves on chain.

MCP trust-related responses: Payment Required — approve or sign, then retry with paymentPayload. Spend Policy Denied — see error.data.spendPolicy for limits and remaining budget.

PATCH /agents/{agentId}/spend-policy
Authorization: X-API-Key (application key)
{
  "enabled": true,
  "budgetUsd": "5.00",
  "period": "daily",
  "hardBlock": true
}

Transfer note: enforce recipient allowlists and transfer limits in your app before signing unsigned transactions from the transfer tool.