Facilitator docs

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.

Pay in more tokens (exact through Permit2, x402 v2): on. The payer signs one Permit2 transfer for the exact price to the x402ExactPermit2Proxy (extra.assetTransferMethod “permit2”), and the money can only go to payTo. Only the tokens on this facilitator’s list are settled, each read on chain first and listed with its decimals and limits under the exact kind in /supported; any other token is refused (unsupported_asset). A payer that has not approved Permit2 for the token gets permit2_allowance_required: approve it once, then pay again. The payee check, the screen, the payment id, the builder code and the receipt work as for exact. Gas sponsoring for the approval (erc20ApprovalGasSponsoring): built, switched off right now.

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. A capture, refund or void of a hold that already exists is never refused by the limits below: only a new payment or a new hold is counted against them. 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. An authorization someone else already settled on chain is answered as settled with its transaction but no receipt (settledVia “observed”): we did not settle it. 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, minAmount): 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. Pass your price as minAmount (USDG base units): without it a payment of any size counts. Details under Endpoints.

Spending budgets (per payer): on. A payer wallet (an agent’s wallet, or its owner) signs its own limits with its own key and sets them with this facilitator (EIP-712, domain “Toll Facilitator Budget”): perPayment, perDay, perPayTo or one cap per payTo, a list of allowed payTos and an end date, in USDG base units, days in UTC. POST https://x402.t0ll.xyz/budget sets or replaces it (a higher nonce wins; only the payer’s own signature counts) or revokes it; GET https://x402.t0ll.xyz/budget?payer= shows it and what was spent today. Verify and settle then refuse a payment past it, on every scheme: exact and upto (the amount actually charged), escrow holds, and batch deposits; error codes start with budget_. Settle holds the amount before anything is sent, so two payments at once cannot both use the last of a day’s budget. A payer with no budget sees no change. Budgets are in USDG: other tokens are refused while one is set.

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. A listing belongs to its payTo: a payment from another wallet that names a seller’s URL is a listing of its own, and it never carries the seller’s verified mark, name or settled count. 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.