--- name: clawd-x402-facilitator description: Spin up your own x402 facilitator on any blockchain, modeled on the Clawd omni-chain facilitator foundation (x402.wtf + the Musebook facilitator). Covers the standard /supported + /verify + /settle contract, per-chain leg recipes (Solana, any EIP-3009 EVM chain, Bitcoin, Lightning, Cardano, and proof-based chains generally), discovery documents, registry listing, test recipes, and the safety rules a facilitator must keep. Use when an agent or developer wants to run, extend, or federate an x402 facilitator. --- # Run Your Own x402 Facilitator — the Clawd Omni-Chain Foundation A **facilitator** is the third role in x402, beside the client (payer) and the resource server (seller): it verifies payment payloads and settles them on-chain so sellers never have to touch a blockchain themselves. One facilitator can serve many chains. This skill teaches you to run one on any chain, the way the Clawd fleet runs its own: - **Reference hub:** https://x402.wtf — one service fronting Solana, Base, Robinhood Chain, HyperEVM, Bitcoin, Lightning, and Cardano legs. - **Reference facilitator:** https://musebook.trade/.well-known/x402-facilitator — discovery document, `/api/x402/supported`, batch settlement, receipts. - **Client-side companion skill:** https://clawdcompute.us/SKILL.md — teach your agent to *pay* x402 first; this skill teaches it to *settle*. Everything here is non-custodial by design: for the standard `exact` scheme the payer signs, you verify and relay. You never sign as the payer's authority and you never hold payer keys. ## 1. The contract you must implement An x402 facilitator is three endpoints plus a discovery document. Amounts are atomic-unit strings (e.g. micro-USDC). Networks are CAIP-2 ids (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, `eip155:8453`, …). | Endpoint | Job | |---|---| | `GET /supported` | List every `{x402Version, scheme, network}` kind you settle, plus signer addresses per network. Resource servers read this to build challenges. | | `POST /verify` | Body: `{x402Version, paymentPayload, paymentRequirements}`. Check the payload is valid, signed by the payer, matches the requirements (asset, amount, payTo, network), and is not replayed. Answer `{isValid: true}` or `{isValid: false, invalidReason}`. **Verify moves no funds.** | | `POST /settle` | Same body. Re-verify, then execute the transfer on-chain (or confirm the payer's broadcast). Answer `{success, transaction, network, payer}` or a structured error. Settle must be idempotent: the same payload settles once. | | `GET /.well-known/x402-facilitator` | Your discovery document: id, schemes, networks, endpoint URLs, extensions. Other facilitators and registries federate from this. | The seller's flow you are serving: seller answers an unpaid request with **402** + a `PAYMENT-REQUIRED` header (the requirements); the client signs a payment payload and resends with `PAYMENT-SIGNATURE`; the seller calls your `/verify`, serves the resource, and calls your `/settle`. Support both x402 v1 and v2 payload shapes if you can — the wire difference is small and the ecosystem runs both. Optional extensions (the Clawd stack ships these; add them when the basics are proven): - **Batch settlement** (`x402m-batch-v0`): one payer signature settles several payments in a single transaction. - **Receipts**: a public, append-only tape of settlements (hash + metadata, never secrets) so anyone can audit what your facilitator settled. - **Prepaid vouchers**: a payer deposits once and signs cumulative vouchers per call; you keep the ledger. Custodial by exception — flag it loudly if you offer it. ## 2. Pick your chains — the leg recipes Every chain leg is one of two patterns. Choose per chain: **Pattern A — signed authorization (`exact`).** The chain's token supports a signed transfer authorization the payer produces off-chain; you verify the signature and relay the execution, paying gas. **Pattern B — payment proof.** The payer broadcasts their own transfer and hands you the proof (txid / preimage); you verify it against an indexer. Stateless and simple; the *resource server* owns replay rejection (a proof is single-use per resource). ### Solana — Pattern A - Asset: USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (6 decimals). - The client builds and signs a transaction containing a `TransferChecked` of at least the required amount to the requirement's `payTo`. - Verify: parse the transaction, confirm the transfer leg (mint, amount, destination), the payer's signature, and a fresh blockhash. - Settle: broadcast the signed transaction — you may co-sign as **fee payer** so the payer needs no SOL — then confirm the **payTo balance delta on-chain**; that delta, not the broadcast receipt, is the authoritative settlement check. ### Any EVM chain — Pattern A via EIP-3009 Works on Base (8453), Robinhood Chain (4663), HyperEVM (999), and any chain whose stablecoin implements `transferWithAuthorization` (USDC does). - The payer signs an EIP-712 `TransferWithAuthorization` (from, to, value, validAfter, validBefore, nonce) under the **token's own EIP-712 domain** — name and version differ per token and chain (Base USDC: `"USD Coin"`, `"2"`; Robinhood USDG: `"Global Dollar"`, `"1"`). Read them from the token contract, never hardcode from memory. - Verify: recover the signer and check it equals `from`; check the nonce is unused on-chain (`authorizationState`); check amount, payTo, and the validity window. - Settle: your **relayer wallet** calls `transferWithAuthorization`. The relayer is gas-only — it holds native gas (ETH, HYPE, …) and nothing else. If the relayer is unfunded, answer **503 with a structured `relayer_unfunded` error** — fail closed, never fake a settlement. ### No desire to run EVM keys? Delegate You may proxy a leg to another facilitator (the Clawd hub delegates its Base leg to Coinbase's CDP Facilitator). Keep the delegation visible: name the backend in a response header (we use `x-facilitator`) and in your discovery notes. Delegation is a routing choice, not a claim that you settle it yourself. ### Bitcoin — Pattern B - The payer broadcasts a BTC transfer to the requirement's address and submits the txid as the payload proof. - Verify via a public indexer (mempool.space / Esplora): the tx pays the required address at least the required satoshis; enforce your confirmation policy (e.g. ≥1 confirmation) before settling. - Settle = attest: return success with the txid once the policy is met. ### Lightning — Pattern B (preimage proof) - The requirement carries a `paymentHash`. The payer pays the invoice and submits the preimage; verify `sha256(preimage) == paymentHash` (cross-check the BOLT11 invoice when one is provided). Settle attests with the hash. ### Cardano — Pattern B - Verify via Koios or Blockfrost: the submitted tx's outputs to the required address sum to at least the required lovelace (or the required `policyId + assetName` quantity for native assets). ### A chain not listed here Ask two questions: (1) Does its stablecoin/token support a signed authorization standard (EIP-3009-like, permit, signed transfer intent)? → Pattern A. (2) Is there a trustworthy public indexer to verify a broadcast transfer? → Pattern B. If neither, you cannot settle that chain honestly — say so in your discovery document instead of listing it. ## 3. Build it — the smallest honest facilitator 1. **Skeleton.** Any HTTPS service works (the Clawd hub is a single Cloudflare Worker; a small Node/Python service is equally valid). Implement `/supported`, `/verify`, `/settle`, and the well-known document for **one chain first**. 2. **Config, not code, per chain:** `{network (CAIP-2), asset, decimals, payTo defaults, RPC/indexer URL, token EIP-712 domain (EVM), confirmation policy (proof legs)}`. Adding a chain should be a config row plus a leg adapter, never a fork of the service. 3. **Keys.** Relayer keys live in your platform's secret store, injected at runtime — never in code, never in the repo, never in logs. One relayer per chain family; gas-only balances; alert on low gas. 4. **Replay protection.** Pattern A: track used EIP-3009 nonces and Solana signatures. Pattern B: record consumed txids/preimages per resource. `/settle` checks the ledger before executing; a duplicate settle returns the original result, not a second transfer. 5. **Errors are a contract.** Structured JSON errors with stable codes (`invalid_payload`, `insufficient_amount`, `nonce_used`, `relayer_unfunded`, `backend_not_configured`). A leg whose backend is missing answers 503 fail-closed — the Clawd hub's Zcash leg does exactly this until its scan backend exists, and its discovery document says so. 6. **Receipts.** Log every settlement (tx hash, network, amount, payTo, timestamp) to an append-only store and expose it read-only. This is your audit trail and your users' proof. ## 4. Discovery and federation 1. Serve `GET /.well-known/x402-facilitator` with your id, schemes, networks, endpoint map, and per-leg status notes. 2. **List yourself in the Musebook registry** so agents can find you: `GET https://musebook.trade/api/x402/catalog` shows the live registry; facilitator entries are also served from `https://musebook.trade/.well-known/x402-facilitator`. 3. Cross-list in the broader x402 ecosystem (x402.org) once a leg is verified live. 4. **Federate:** accept `forwardTo` on settle-family calls and carry `facilitator` / `forwardedBy` fields on receipts, so facilitators can route to each other instead of every seller integrating everyone. ## 5. Prove each leg before you claim it A leg is **live only when its path is complete and verified against the real network** — discovery statuses are the truth of the code path, not marketing. Run these smoke tests per leg and keep the results: - Bogus payload → structured rejection from `/verify` (never a 500). - A value-0 (or minimum-amount) authorization from a throwaway wallet → `/verify` returns `isValid: true`; `/settle` either settles it or returns the honest gated error (e.g. `relayer_unfunded`). - A known historical transaction on proof legs → verifies; the same proof with amount +1 → `insufficient_amount`. - Replay the same payload at `/settle` twice → one settlement, one result. - `GET /supported` and the well-known document match what the tests proved — no more, no less. ## 6. Rules a facilitator lives by - **Non-custodial for `exact`:** the payer signs; you verify and relay. If a scheme makes you custodian (prepaid vouchers), label it as such. - **Never claim a chain you cannot settle.** A gated leg says gated, in the discovery document itself. - **Fail closed.** Missing backend, unfunded relayer, stale indexer → structured 503, never a guessed success. - **Verify is not settle.** Never move funds on `/verify`; never report a settlement you did not confirm on-chain (Pattern A: the payTo delta; Pattern B: the confirmation policy). - **Keys stay secret.** Relayer and payout keys never appear in chat, code, logs, or discovery documents. - **Fees are explicit.** If you charge a facilitator fee or sponsor gas, state it in the discovery document; the 402 challenge amount a client signs must always equal what the seller quoted. ## Foundation & references - The Clawd omni-chain hub (live legs + statuses): https://x402.wtf and its `/.well-known/x402-facilitator` - Musebook facilitator (batch, receipts, registry): https://musebook.trade/.well-known/x402-facilitator · `GET https://musebook.trade/api/x402/catalog` - The official x402 guide (start here if x402 itself is new): https://clawdcompute.us/x402-guide - Pay-side skill for your agent: https://clawdcompute.us/SKILL.md - Upstream protocol: https://www.x402.org · spec + code (Apache-2.0, stewarded by the x402 Foundation): https://github.com/x402-foundation/x402 - Check how any facilitator or paid API treated other agents before you route volume through it: https://api.402reviews.xyz (see the pay-side skill for the check/review flow). *Built on the Clawd z402 omni-chain foundation: one facilitator, one discovery document, every chain a leg — transparent about what is live, what is gated, and what is still being built.*