Concepts

Burnbound sits between an AI agent and the x402 APIs it pays. This page explains the pieces: agents, policies, caps, allowed hosts, human approvals, signing modes, and how an x402 v2 payment flows through them.

What is Burnbound?

Burnbound is a buyer-side spending control plane for AI agents that pay x402 APIs. Before your agent pays, Burnbound checks the payment against rules you set: which hosts it may pay, how much per payment, how much per day, and when a human must approve. Only allowed payments are signed, by a wallet you bring.

Burnbound is not a wallet, not an x402 facilitator and not a seller paywall. It never holds private keys or funds, and it never settles payments: sellers do.

What is an agent?

An agent is one identity that pays: it has its own policy, its own keys (bb_agent_…) and its own wallet connection. Use one Burnbound agent per AI agent or workload, so caps, approvals and audit stay separate.

An agent key can only act for its own agent: read its budget and payments, ask to authorize a payment, report a receipt and check its own approvals. It cannot change rules, approve payments or create keys. Those actions need a human signed in to the dashboard.

What is a policy?

A policy is the set of rules Burnbound evaluates for every payment of an agent. A payment is allowed only if it passes every rule; otherwise it is denied, nothing is signed, and the decision is recorded with the reasons.

Every agent's policy has:

• Allowed hosts: the hosts the agent may pay.
• Maximum per payment (maxUsdPerTx) and daily cap (dailyCapUsd), in USD.
• Allowed networks and assets: new agents pay USDC on Base.

Optional rules, off by default, can be turned on per agent:

• Challenge rules: extra host patterns, path prefixes and a maximum amount for what the seller's 402 may ask.
• Velocity: a maximum number of payments, or a maximum USD amount, per time window (60 seconds by default).
• Step-up approval: a USD threshold from which a human must approve (see below).

Policies are versioned. Changing the hosts or the caps creates a new version, and each decision records the version it used (policyVersion).

Which reasons can a denial have?

A denied payment carries one or more reason codes. The MCP tool fetch_paid returns them in reasons of a policy_denied error, and the dashboard audit shows them.

How do allowed hosts work?

Allowed hosts are the only hosts an agent may pay. An entry is either an exact host (api.example.com) or a wildcard (*.example.com), which matches any subdomain such as data.example.com but not example.com itself. With an empty list, no payment is allowed.

The policy runs on the host of the URL that answered 402, and the seller's x402 challenge must name a resource on that same host. The MCP server also checks the list before it sends anything: fetch_paid never requests a URL whose host is not allowed, paid or not (host_not_allowed).

How do the spending caps work?

Each agent has two caps: a maximum per payment and a daily cap. A payment over the per-payment maximum is denied (amount_exceeds_per_transaction), and so is a payment that would take today's spend over the daily cap (daily_cap_exceeded).

• The day is the UTC calendar day.
• Today's spend counts payments that were authorized, submitted, pending settlement or settled. Failed and expired payments do not count.
• At 80% of the daily cap the agent's cap level becomes warning, and at 100% exhausted (capLevel in get_budget; the dashboard shows a badge).
• fetch_paid also takes a per-call maxAmountUsd, checked by the MCP server on top of the policy.

Your plan adds a monthly limit on managed spend for the whole organization: 50 USD per calendar month (UTC) on the Free plan, no limit on Pro. Past it, payments fail with plan_limit_reached.

How do human approvals work?

With step-up approval on, any allowed payment at or above the agent's threshold waits for a human instead of being signed. fetch_paid returns pending_approval with an approvalId; a human approves or denies it in the dashboard; the agent then retries with the same idempotencyKey and is never charged twice.

1. The agent calls fetch_paid. The amount is at or above the threshold, so the result is status: "pending_approval" with approvalId and idempotencyKey.
2. A human sees the payment in the dashboard's approvals inbox (amount, host, payee, network) and approves or denies it.
3. The agent polls get_approval_status with the approvalId.
4. When it is approved, the agent calls fetch_paid again with the same url, method, headers, body and idempotencyKey. If it is denied or expired, the agent must not retry it.

Details:

• The approval threshold is checked only after the other rules: a payment that breaks a rule is denied, not sent for approval.
• A pending approval expires after 15 minutes by default. An owner can set this between 5 minutes and 24 hours in the dashboard settings.
• Once approved, the agent has 10 minutes to retry the payment.
• At most 5 approvals can be pending per agent and 20 per organization; past that, fetch_paid returns approval_queue_full.
• Notifications: the approvals inbox is on every plan. On Pro and Team, Burnbound can also notify you through a Slack incoming webhook and by email to the organization's owners.

Which signing modes are there?

Burnbound never signs with a key it holds. Each agent's wallet is connected in one of two modes: Coinbase CDP, where the key stays with Coinbase and Burnbound requests each signature, or client-side signing, where the key stays on your machine and the MCP server signs locally after Burnbound allows the payment.

In client-side mode, before it signs, the MCP server checks that the local wallet is the one registered for the agent, that what it is asked to sign is one of the seller's own offers for the host that asked, that the amount is within maxAmountUsd, and that the authorization window is short (at most 300 seconds). It only signs USDC TransferWithAuthorization (EIP-3009) on Base or Base Sepolia.

How does an x402 v2 payment flow through Burnbound?

The buyer signs and the seller settles. Your agent asks for a URL, the seller answers HTTP 402 with a price, Burnbound decides, your wallet signs a USDC transfer authorization, and the seller submits it on-chain through its facilitator. Neither your agent nor Burnbound ever calls a facilitator's settle endpoint.

1. The agent calls fetch_paid with a URL. The MCP server checks that the host is allowed and requests the URL.
2. The seller answers 402 Payment Required with a PAYMENT-REQUIRED header (x402 v2): price, network, asset and payee.
3. The MCP server sends that challenge and the URL to Burnbound, with an idempotency key for this purchase.
4. Burnbound evaluates the agent's policy and answers allow, deny or step-up. An allowed payment is recorded and counts against the daily cap from that moment.
5. The payment is signed as an EIP-3009 TransferWithAuthorization for USDC. With Coinbase CDP, Burnbound asks CDP to sign and returns the signed payload. With client-side signing, Burnbound returns exactly what to sign (the seller's offer, a nonce derived from the payment, and a short validity window) and the MCP server signs it locally.
6. The MCP server retries the same request once, with the PAYMENT-SIGNATURE header. It never follows a redirect after paying.
7. The seller verifies and settles the payment through its facilitator, and answers with the resource and a PAYMENT-RESPONSE header.
8. The MCP server reports that answer to Burnbound as a receipt. Burnbound checks the transfer on-chain before it marks the payment settled.

What is an idempotency key?

An idempotency key identifies one purchase attempt. Burnbound never charges twice for the same key: a repeated request with the same key replays the earlier decision (replayed: true in the result) instead of signing a new payment.

fetch_paid creates a new key for every call. Pass idempotencyKey only to retry a purchase: after a pending_approval was approved, or after a payment_outcome_unknown error. A key reused for a different request fails with idempotency_key_reused.

What does Burnbound record?

Every decision and every payment is recorded in an audit log: allowed, denied (with reasons), pending approval, approved or denied by whom, signed, settled or failed. The dashboard shows spend per agent, each payment with its on-chain transaction, and the audit. The Free plan keeps 30 days of audit, Pro 365 days.