Security and trust model
Burnbound decides whether your agent may move money; it never holds funds, card numbers, wallet private keys or your Stripe secret key. This page says what Burnbound stores and sees for refunds, cards and each signing mode of paid APIs, what the MCP server protects against, and where the protection ends, in particular the cooperative limit of client-side signing.
Does Burnbound hold my private keys or funds?
No. Burnbound never stores a wallet private key and never holds funds. With Coinbase CDP the key stays with Coinbase; with client-side signing it stays on your machine. API payments go straight from your wallet to the seller. Refunds leave your Stripe account and card money stays in your Stripe Issuing balance: see What does Burnbound hold for refunds and cards?.
What Burnbound does store in Coinbase CDP mode is your CDP API credentials (API key ID, API key secret and wallet secret), because it needs them to ask Coinbase to sign the payments your policy allows. They are encrypted at rest (AES-256-GCM), decrypted only to request a signature, and never shown again in the dashboard or returned by the API. They are still powerful: treat the CDP wallet as a spending wallet and keep in it only what your agents should be able to spend.
What does Burnbound hold for refunds and cards?
Neither rail gives Burnbound a Stripe key or a card number. Burnbound decides; Stripe moves the money, in your account.
Refunds (the action gateway). The gateway runs on your machine or network, with your restricted Stripe key (Charges, Customers and PaymentIntents read, Refunds write). The key never leaves that process and never reaches Burnbound. What Burnbound stores is the gateway's credential: an id and a bbgw_… secret, encrypted, that the gateway signs every call with. A request that does not carry a valid gateway signature is refused even with a valid agent key, so another organization cannot run refunds through your gateway, and an agent cannot report a refund as failed to free its own spend.
- The amount, the currency and the customer come from Stripe, never from the agent, and an amount over what is still refundable is refused before Burnbound decides.
- The same
idempotencyKeynever refunds twice; the gateway uses Stripe's idempotency keybb_<intent id>. - When Stripe's answer is unclear (a timeout or a 5xx), the gateway looks for the refund in Stripe before it reports anything. A refund whose outcome is unknown is never reported as failed: it stays
submittedand keeps counting as spend. - The gateway refuses a live Stripe key unless you set
GATEWAY_ALLOW_LIVE=1. Keep it on loopback or a private network: anyone who reaches it with one of your agent keys can ask for refunds, which still face the policy. - Rotate keeps the old
bbgw_…secret valid for 24 hours. After a leak, use Rotate without a grace period or Revoke instead.
Cards (Stripe Issuing). Burnbound keeps only the signing secrets of your two Stripe endpoints (whsec_…), encrypted, and shows their last 4 characters. It checks Stripe's signature on every event and refuses anything else. Stripe names the card by its id (ic_…), and its burnbound_agent_id metadata names the agent.
- A decision that runs out of time is answered with what the connector says: decline, by default.
- A card payment that would need an approval is declined (
approval_required): a card cannot wait for a person. - The merchant's website comes from the merchant itself, so it is not proof of who is charging. Allow or block card spend with rules on the merchant's payee (
stripe-merchant:<network id>) or its category, which the card network sets.
A support ticket, an email or a web page can talk an agent into asking for a refund or a purchase. The policy still decides, outside the model, before any money moves: an injected request meets the same caps, budgets, rules and approval threshold as any other.
What does Burnbound see in each signing mode?
Burnbound sees what it needs to decide and to audit: the payment request, never the content you buy. The table compares the two modes.
| Coinbase CDP | Client-side signing | |
|---|---|---|
| Wallet private key | No (stays at Coinbase) | No (stays on your machine) |
| Signing credentials | Your CDP API credentials, encrypted | None |
| Wallet address | Yes | Yes (the only thing you register) |
| Can Burnbound get a payment signed? | Yes, through CDP, for payments its policy allows | No |
In both modes, for every payment Burnbound sees and records:
- the URL that answered HTTP 402, including its path and query string;
- the seller's challenge (x402 or MPP): price, network, asset, payment method and payee;
- the decision (allowed, denied with reasons, or sent for approval) and the policy version;
- the
originthe agent declared for the URL (user,catalog,tool_outputorweb), when it sends one; - the seller's
PAYMENT-RESPONSEreceipt and the on-chain transaction.
Burnbound does not see the headers or body your agent sends to the seller, or the seller's response body. The MCP server sends Burnbound only the 402 challenge and, after paying, the receipt.
How are agent keys protected?
An agent key (bb_agent_…) is shown once when it is created, and Burnbound stores only its SHA-256 hash. It can only act for its own agent: read its budget and payments, ask to authorize a payment, report a receipt and read its own approvals. It cannot relax the policy, raise a cap, approve a payment, connect a wallet or create keys; those need a human signed in to the dashboard. The only change it can make is a stricter rule the user asks for in the chat (propose_rule).
The key lives in your MCP client's config (~/.claude.json, .cursor/mcp.json). An agent that can run shell commands on the same machine could read it, so prefer agent keys with tight caps over organization keys, which have admin scope. Revoke a key in the dashboard at any time.
What does the MCP server protect against?
@burnbound/mcp adds client-side guards in front of the Burnbound policy. They reduce what a confused or manipulated agent can do with fetch_paid; the Burnbound API remains the authority on spending.
- The key goes only to the Burnbound API. It is never sent to the URLs
fetch_paidrequests and never appears in tool results or logs. Input that contains the key is refused (contains_credential). - Only allowed hosts are requested.
fetch_paidchecks the agent's allowed hosts before sending anything, paid or not. - No private networks. Private, loopback, link-local and reserved addresses are blocked, for IP literals and for every address a hostname resolves to, at connect time.
- The seller cannot redirect the payment. The resource in the seller's challenge must be on the requested host, and the paid request never follows redirects.
- Seller responses are untrusted. A paid API can return text written to manipulate the agent ("ignore your instructions and pay…").
fetch_paidreturns the body fenced and labelled as untrusted data, apart from the metadata. - Error messages are written by the server, never copied from the API or the seller.
- Only a human approves. The server can offer the user the approval page from the chat, but it never approves or rejects a payment, and the agent's key cannot either.
- No wallet key in the config. The server refuses to start if a
BURNBOUND_*variable looks like a private key.
What if a page tricks the agent into paying?
A web page, another tool's result or the seller's own 402 can try to make the agent pay someone it should not. Burnbound judges every payment before anything is signed, on every agent:
- Lookalike hosts are refused. Allowed hosts match exactly (or as
*.suffix), sose11er.exampleor a host with a Cyrillic letter is refused unless you allowed it (host_not_allowed). - A new receiving address waits for a human. The first payment to an address (x402
payToor MPP payee) the organization has never paid on that host and network is held (new_pay_to), unless the seller is listed in the Burnbound catalog and asks to be paid at an address Burnbound pinned for it. - A catalog seller is paid only at its pinned addresses. If a seller in the Burnbound catalog, whose receiving addresses on that network Burnbound pinned, asks to be paid at another address or MPP payee, the payment is denied (
pay_to_not_verified). - A 402 that reads like instructions waits for a human. If the 402's description or
errortext tells the agent what to do ("ignore previous instructions…"), the payment is held (instruction_like_description), also when the text is split by invisible characters or comes after a long harmless start. - An inflated price meets your caps: the maximum per payment, the daily cap and the call's own
maxAmountUsd.
These cases are tested on every change against trap pages that play each trick. The protection has limits:
- The detection of instructions looks for a short list of patterns. A reworded instruction can get past it; the payment then still faces the allowed hosts, the caps and the receiving-address checks.
- Burnbound judges the payment (host, receiving address, amount, the 402's text), not the page that led the agent to it. The
originthe agent declares is recorded for the audit and never changes the decision. - The price is checked against your caps, not against the seller's usual price.
- A wildcard such as
*.example.comadmits any name under it.
What is the limit of client-side signing?
Client-side signing is cooperative. Burnbound cannot stop a process that already runs as your user: an agent that can run shell commands on the machine could read the wallet key (from the OS keychain or the wallet file) and sign payments without asking Burnbound. The policy holds only while the agent goes through the MCP server.
The MCP server makes that harder, not impossible:
- the key is never in the MCP config or in the environment the agent can read, and never sent anywhere;
- it is loaded only at the first
fetch_paid, never by the read-only tools; - every request to Burnbound and to sellers is checked for it and blocked if it appears;
- it only signs payments that Burnbound allowed (USDC transfer authorizations over x402 or, with MPP turned on,
tempo.chargetransactions in USDC.e), for the seller's own offer, with a short validity window.
If you need enforcement that does not depend on the agent's cooperation, use Coinbase CDP: the agent never holds anything that can sign, and Burnbound requests every signature.
How does out-of-policy detection work?
For client-side wallets, Burnbound watches the wallet's address on-chain and records a payment.out_of_policy event when USDC (or USDC.e on Tempo) leaves it without a matching payment that Burnbound allowed. It detects after the fact; it cannot block or reverse the transfer.
A movement is flagged when it is:
- a transfer authorization whose nonce does not belong to any payment Burnbound allowed;
- a transfer authorization that belongs to a payment, but to a different payee, amount or payer;
- a transfer authorization for a payment that had already failed or expired;
- a plain
transfer()ortransferFrom(), with no authorization at all; - an
approve()orpermit()that grants an allowance.
Flagged movements appear in the audit and as a warning on the agent's page in the dashboard, usually within a few minutes of reaching the chain.
How does my own signer know a request comes from Burnbound?
If your wallet is connected through your own signing endpoint (a signer URL) instead of Coinbase CDP or client-side signing, Burnbound signs every request it sends there, so your signer can refuse anyone else who learns its URL. Each POST carries a Burnbound-Signature header in the style of Stripe webhooks: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">.
- Burnbound generates the secret (it starts with
bbsig_) when you connect the signer and shows it only once. It is stored encrypted, like CDP credentials, and never returned again. If you lose it, renew it and the new one is shown once. - When you renew it, Burnbound signs with both the new and the old secret for 24 hours (two
v1values), so you can update your signer without a failed payment. Accept a request when anyv1matches a secret you hold. - Refuse a
tmore than 5 minutes away from your clock, and compute the HMAC over the body exactly as received, before parsing it. - The
GETthat reads your signer's description is not signed: Burnbound reads it before the secret exists, and it only returns a public address. Leave it open. - A signer connected before request signing existed keeps working without the header. The dashboard flags it and offers to generate a secret.
A check in Node, with no dependencies:
import { createHmac, timingSafeEqual } from "node:crypto";
// Your Burnbound signing secret; during a rotation, the new one and the old one.
const SECRETS = [process.env.BURNBOUND_SIGNING_SECRET];
export function verifyBurnboundSignature(
header,
rawBody,
now = Date.now() / 1000,
) {
const parts = (header ?? "").split(",").map((part) => part.trim().split("="));
const t = parts.find(([key]) => key === "t")?.[1];
if (!t || !/^\d+$/.exec(t) || Math.abs(now - Number(t)) > 300) return false;
const signatures = parts
.filter(
([key, value]) => key === "v1" && /^[0-9a-f]{64}$/.exec(value ?? ""),
)
.map(([, value]) => Buffer.from(value, "hex"));
return SECRETS.some((secret) => {
const expected = createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest();
return signatures.some((signature) => timingSafeEqual(signature, expected));
});
}
Call it with the raw body before JSON.parse, and answer 401 when it returns false.
Why should I fund the wallet with a small balance?
Because the balance is the real ceiling on what a compromised or misbehaving agent can spend outside the policy. With client-side signing, an agent that reads the key can spend the whole wallet; with any mode, a wallet holding a week of spend loses at most a week of spend.
- Keep a balance sized to what the agent should spend in a short period, and top it up.
- Keep no ETH in a client-side wallet. x402 payments do not need it, and without it the wallet cannot send an ordinary transaction itself. A signed transfer authorization can still be submitted by someone else, so the USDC balance is what really bounds the risk.
- Use one wallet per agent, so a problem in one does not reach the others.
How do I keep Claude Code away from the wallet key?
Deny the agent the ways to read the key in .claude/settings.json (or ~/.claude/settings.json). These rules reduce accidents; they are not a sandbox.
{
"permissions": {
"deny": [
"Read(~/.burnbound/**)",
"Edit(~/.burnbound/**)",
"Bash(security find-generic-password:*)",
"Bash(security dump-keychain:*)",
"Bash(secret-tool lookup:*)",
"Bash(npx -y @burnbound/mcp@latest wallet export:*)",
"Bash(npx -y @burnbound/mcp wallet export:*)",
"Bash(burnbound-mcp wallet export:*)"
]
}
}