x402How x402 guarding works
How x402 guarding works
An x402 buyer wallet that pays only what the owner's mandate allows and proves it to the seller.
An agent pays x402 sellers from a guarded Safe. The agent holds one owner seat. Each member of Exchain's attested quorum (the signing enclaves) holds another. Exchain co-signs only payments that fit the mandate.
x402 decides how an agent pays; Exchain decides whether this agent may pay this seller this amount.
What the guarded Safe gives you
| Property | How | Details |
|---|---|---|
| Required co-signature | The Safe threshold is all owners. No payment exists without Exchain | Register a Safe |
| Seller binding | Payments are held to sellers' signed offers | Seller binding |
| Guard receipt | Every co-signed payment carries a receipt the seller can verify | Guard receipt |
| Owner exit | The owner module withdraws, rotates the agent or removes Exchain, with no Exchain signature | Owner controls |
Who controls the Safe
| Party | Role in the Safe | What it can do |
|---|---|---|
| Owner address | The only module | Withdraw, rotate the agent, remove Exchain. No Exchain signature |
| Agent key | One owner | Signs every payment |
| Attested quorum | One owner per member | Co-signs payments within the mandate |
| Safe | Holds the stablecoins it governs | Its balance is the most the agent can spend |
Integrate a buyer
Keep your x402 client, your facilitator and @x402/evm's ExactEvmScheme. Give the scheme a signer whose address is the Safe. Its signTypedData(typedData) does four things:
Hash
Compute the Safe message hash of the typed data.
Agent signs
The agent key signs that hash: a raw 65-byte signature, not personal_sign.
Co-sign
Send POST /v1/x402/cosign with the typed data, the agent signature and the intent. When the seller sent a signed offer, copy it from the 402 at extensions["offer-receipt"].info.offers[i] into intent.offer.
Return and attach
On 200, return signature from the answer. Put receipt into the payment payload at extensions["exchain-guard"].receipt.
Request and response fields: Co-sign a payment.
Client cap
From @x402/* 2.29, the client refuses any payment above $1 before your signer runs. On a guarded wallet, set spendControls.maxAmountPerPayment to at least the mandate's perTxCap, or to false. The mandate is then the cap, and an over-cap payment returns a 409 with a decision id.
Handling answers
| Answer | Meaning | Do |
|---|---|---|
200 | Co-signed | Return signature, attach receipt |
409 | Refused before anything was signed | Fail the payment. Show the code and decisionId (Refusals) |
402 fee_due | Exchain's fees are due. Nothing was decided | Settle fees, then send the same request again |
503 quorum_unavailable | Nothing was consumed | Retry after Retry-After |
Settlement
Any x402 facilitator settles the payment. Exchain is not a facilitator. The token, or Permit2, checks the Safe signature through ERC-1271. Ethereum USDT and Polygon USDT0 pay x402 sellers through Permit2 only, so register the Safe with a permit2Cap to use them: Permit2.