Facilitator docs

How it works

Verify checks the payer’s EIP-3009 signature (the exact scheme, x402 v1 and v2), that it pays exactly the amount to payTo, that it is valid now, that its nonce is unused and the payer holds the USDG. Then it runs the payee check and returns the outcome.

Payee check (ERC-8478): payTo is compared with the agent wallet of the seller’s registered ERC-8004 identity. A payTo that does not match is flagged; it does not block a payment unless this facilitator is set to refuse it (it is set to refuse it right now), and an identity that could not be read is never a reason to refuse.

Settle simulates the transfer first, then sends one transaction per payment, even when the same payment is sent twice. A transaction not mined in 30 s answers settlement_pending with its hash: ask again with the same payment. A payment that carries a payment id is paid once per payer, seller and id: a second authorization for the same id within 24 hours answers duplicate_payment with the earlier transaction.

Upto (x402 v2, pay for what is used): on. The payer signs a maximum through Permit2 for this facilitator’s wallet, the seller settles what it used, never more than the maximum, and 0 sends no transaction. /supported lists it, with the wallet to sign for.

Safety screen (check_tx on every payment): on. A payment that passes the checks above is also read by check_tx, the same pre-sign check agents call, and the seller gets ALLOW, WARN or BLOCK with the warning codes in extensions.screen of the verify and settle answers. A BLOCK is flagged, not refused. A check not read within its time limit answers not-read and the payment goes on.

Escrow with refunds (auth-capture, x402 v2): on. The payer’s USDG is held in the v1.0 escrow contract for up to 7 days; the seller captures what it is owed, voids the rest back to the payer, and can refund what it captured with its own USDG, each step a /settle call with payload.type, signed by the seller’s own key. After the capture deadline the payer can reclaim what is still held, straight from the escrow. Every hold and step is listed on the activity page.

Sub-cent payments (batch-settlement, x402 v2): on. The payer deposits USDG into a channel on the x402BatchSettlement contract once, then signs a running total for each request: a request sends no transaction and pays no gas, and this facilitator claims many channels in one transaction later. The seller brings its own refund key; what is not charged goes back to the payer, by a refund the seller signs, or by the payer’s own withdrawal after a 1-day delay.

Receipt: a settled payment comes with a signed receipt (EIP-712, “Toll x402 Receipt”) with who paid whom, how much, the transaction, the resource and the payee check’s outcome. Look one up.

Offer and receipt (x402 extension): when a payment carries the seller’s signed offer, the settle answer says who signed it, whether that is the payTo, and whether the terms match, and hands the seller the spec’s receipt payload to sign with its own key. The receipt is the seller’s to sign; Toll does not sign it.

Paid before: GET https://x402.t0ll.xyz/paid?payer=&payTo= (optional resource, since): whether a wallet already paid this payTo here (settlements, escrow captures, batch charges), so a seller using sign-in-with-x can let a returning wallet in without charging again. Details under Endpoints.

Builder code (ERC-8021): on. Every settlement transaction carries an ERC-8021 builder code (“toll”, plus the seller’s app code when its payment sends one, the appCode option of @tollxyz/x402-seller) at the end of its calldata, so explorers and dashboards can count volume per app and facilitator. The transfer itself is unchanged.

Discovery (x402 bazaar): every paid x402 API on Robinhood Chain, verified payees first, at https://x402.t0ll.xyz/discovery/resources and https://x402.t0ll.xyz/discovery/search, the find_paid_api MCP tool and the discover page. The list is read from the agent census; recording sellers' own bazaar descriptions is built, switched off right now.

Paying, not selling? Before an agent signs an upto or auth-capture payment for any seller, check_tx reads it from the payer’s side: the most an upto seller can charge, and an auth-capture payment’s escrow, token collector and hold. The full list: what Toll checks.

On every settlement

• Payment-id dedupe. A payment id from one payer to one seller settles once in 24 hours; a second authorization for it answers with the first transaction.
• Gas paid by us. The facilitator’s wallet sends the transaction and pays its gas; payer and seller pay none.
• No fee. The seller receives the full amount the payer signed.

Limits

Limits: 0.001 to 100 USDG a payment; at most 200 settlements a day for one payTo; a payee that does not match is refused; payments from smart-contract wallets (ERC-1271) are not settled here. What it cannot do: a requirement with its erc8004 field removed, or a payment sent through another facilitator, is not checked here.

Endpoints

POST https://x402.t0ll.xyz/verify and POST https://x402.t0ll.xyz/settle take the x402 body (v1 or v2) and answer the x402 shapes, with the payee check in extensions.erc8478 and the receipt in extensions.receipt. GET https://x402.t0ll.xyz/supported lists what it settles; GET https://x402.t0ll.xyz/receipt/<id or tx> returns one settlement; GET https://x402.t0ll.xyz/stats the live numbers and escrow totals; GET https://x402.t0ll.xyz/discovery/resources and /discovery/search the paid APIs. GET https://x402.t0ll.xyz/paid?payer=&payTo= (optional resource, since): whether a wallet already paid this payTo here (settlements, escrow captures, batch charges), so a seller using sign-in-with-x can let a returning wallet in without charging again. The same endpoints are also served under https://t0ll.xyz/api/facilitator.