Agents
External x402 merchants
Tollex can buy from x402 services it does not run. Your wallet pays the merchant directly, the live price is checked against your plan before you sign, and Tollex adds no fee.
An agent does not need to know which service will answer its request. With includeExternal set, resolve considers verified third-party x402 resources next to Tollex’s own capabilities, under the same limits and policy. If one of them is the best eligible route, do() buys it the same way it buys anything else, and the result says so: origin is EXTERNAL_X402 and external.merchant names who ran it.
How a purchase works
| Step | What happens |
|---|---|
| Discovery | A listing (an x402 Bazaar catalogue or a seed) is challenged with an unpaid request. Only a resource that answers with a valid x402 v2 402 enters the catalogue, with its payment options recorded exactly as the merchant stated them. |
| Resolve | External resources are evaluated only when the request sets includeExternal, through the same hard gates as every other capability: price, network, asset, scheme, providers, side effects, freshness, health, latency and receipt requirements. The plan binds the exact payment option it chose (route.requirementsHash) and the merchant's own address (route.payTo). |
| Live terms | Before anything is signed, the service asks the merchant again. Only an option identical to the planned one is passed to your wallet. Anything else stops the purchase with PAYMENT_REQUIREMENTS_CHANGED. |
| Your policy | Budgets, allow lists, the approval hook, the spend reservation, the operation journal and the mainnet gate apply exactly as they do for Tollex capabilities. There is no separate payment path. |
| Payment | Your wallet signs one authorization for the merchant's amount to the merchant's payTo. The service forwards it once, to the merchant's verified URL only. The merchant settles it through the facilitator it chose. |
| Reconciliation | Tollex reads the outcome from the chain: the authorization's state on the token or Permit2, the settlement transaction, and the transfer it made. |
| Result | The result comes back with the merchant's identity, the payment and delivery states and a signed route evidence document. |
Who receives the payment
The merchant receives exactly the amount in its live 402, at the address in its live 402. Tollex receives nothing: the authorization the wallet signs names the merchant as recipient, and the service refuses to forward any authorization whose recipient or amount differs from the merchant’s terms. Tollex currently adds no platform fee to externally routed x402 payments. Network fees follow the scheme: for exact and upto payments the merchant’s facilitator submits the transaction.
What is checked before you sign
| Check | On failure |
|---|---|
| The merchant answers with a decodable x402 v2 402 | Not payable; nothing signed. |
| An option is identical to the planned one: scheme, network, asset, payTo, amount, timeout and extra | PAYMENT_REQUIREMENTS_CHANGED; the response lists the fields that differ. Resolve again after discovery re-checks the merchant. |
| Your signing policy allows it | POLICY_REJECTED. |
| The network is not Robinhood Chain mainnet, unless the operator enabled mainnet writes | POLICY_REJECTED; refused by the client and by the service. |
| The scheme is exact or upto, on a network the service can reconcile | SCHEME_INCOMPATIBLE or NETWORK_INCOMPATIBLE in the plan. |
Discovery metadata is never authority to spend. Names, descriptions and tags written by a merchant are display text: they are bounded, stripped of control and bidirectional characters, and have no effect on price, network, recipient or policy.
Schemes
exact payments work with EIP-3009 transfer authorizations and with Permit2. upto payments use Permit2 and need an allowance, which the plan lists as a precondition; the merchant charges what it measured, never more than the signed maximum. batch-settlement is not supported for external merchants, because a payment channel is bound to the merchant’s own receiver authorizer; such resources are rejected with SCHEME_INCOMPATIBLE. Tollex never rewrites a payment to fit a facilitator it controls.
When something goes wrong
| Situation | What you get |
|---|---|
| The merchant cannot be reached before payment (DNS, TLS, refused connection, unsafe address) | A transport or policy error. When the authorization was signed but provably never left the service, nothing is charged. |
| The connection drops after the authorization was sent | SETTLEMENT_PENDING. Tollex reads the chain before doing anything else and only ever resends the same authorization. Never sign again; query the operation. |
| The merchant was paid but returned an error, too much data or nothing | EXECUTION_FAILED with the amount charged and the evidence. Payment and delivery are recorded separately; Tollex does not invent a refund. |
| The merchant redirects the paid request | The redirect is not followed and the authorization goes nowhere else. |
| The same request is sent twice, or many times at once | One forward and one payment; later copies get the recorded outcome. |
Route evidence
Tollex did not run the merchant’s service, so it does not issue an execution receipt for it. It issues route evidence instead, in the TOLLEX-EXTERNAL-EVIDENCE header: an EIP-712 document under its own domain, “Tollex External Route Evidence”, signed by the service’s published receipt key. Every field is labelled with where its truth comes from.
| Source | Fields | Meaning |
|---|---|---|
TOLLEX_OBSERVED | resource, requirements, authorization id, authorized amount, platform fee, request and response hashes, HTTP status, timings | What the Tollex service saw and compared. |
ONCHAIN_VERIFIABLE | settlement transaction, block, the address that settled, the amount transferred | Checked by Tollex on chain, and checkable by anyone. |
MERCHANT_STATED | hashes of the merchant's payment response and of any receipt it sent | What the merchant stated. Recorded, never presented as Tollex's claim. |
Verifying it needs only the published domain, the key set at /.well-known/tollex-receipt-keys and RFC 8785 canonical JSON, the same recipe as a receipt. The receipts page describes it.
Limits
- Tollex cannot vouch for what a merchant returns. External output is always marked as untrusted data.
- A merchant that receives an authorization can still settle it until it expires, even after reporting a failure. Tollex keeps watching the chain and records it if that happens.
- Reputation for external merchants comes only from what Tollex observed on its own routes, with sample counts. Nothing is imported or scored for them.
- External execution is an operator setting. A service without it plans external resources but refuses to buy them with
EXTERNAL_EXECUTION_NOT_CONFIGURED.