x402 multi-network readiness: a provider test guide
A provider-focused checklist for CAIP-2 identifiers, assets, facilitators, signers, test environments, and evidence across network families.
DIRECT ANSWER
An x402 service is multi-network ready only when each advertised option works end to end: the CAIP-2 identifier is canonical, the asset and decimals are correct, the buyer signer and server scheme match, a facilitator supports verification and settlement, test and production environments are separated, and an exact-route paid call returns the promised result on every listed network.
Key takeaways
- Use full CAIP-2 identifiers in protocol data; display names such as Base or Solana are labels, not sufficient machine identifiers.
- Readiness is the intersection of scheme, network, asset, signer, facilitator, server, and buyer support rather than a chain logo.
- Test each payment option independently and publish route-level evidence without merging testnet and mainnet results.
What multi-network readiness actually means
Multi-network readiness is not the ability to place several network names on a listing. For one protected route, the server must produce a valid payment requirement for each advertised option, a compatible buyer must sign it, the facilitator or local implementation must verify and settle it, and the retried request must return the promised resource. A failure in any component makes that option unavailable even when the network itself is healthy.
Treat every network option as a small compatibility matrix. Record the protocol version, payment scheme, CAIP-2 network identifier, asset identifier, amount encoding, signer type, facilitator, server package, buyer package, and test date. Shared application code can reduce duplication, but the evidence remains option-specific because EVM, SVM, and other network families use different signatures, asset models, and settlement paths.
Use CAIP-2 identifiers as protocol data
x402 v2 uses CAIP-2-style identifiers to name networks without relying on ambiguous display labels. Base mainnet is eip155:8453, while Solana mainnet uses a solana namespace and a chain reference. The namespace identifies a blockchain ecosystem and the reference identifies a particular chain. Store and compare the full value; do not normalize every network to a word such as base, mainnet, or solana.
Validate identifiers at configuration boundaries. A seller should reject an unknown or malformed network instead of silently selecting a default. A buyer should compare the received identifier with its allowlist before creating a signature. Keep friendly labels in the interface, but retain the canonical string in logs and evidence. That prevents the same display name from hiding a testnet, fork, legacy alias, or unsupported chain.
Verify asset contracts, mints, and decimals
A dollar display price is not enough to execute a payment. The payment requirement must identify the asset and encode the amount in the unit expected by that asset. Official x402 documentation lists default assets for selected networks, but a default is a convenience rather than a universal property of the chain. Custom assets require explicit configuration and support through the chosen payment mechanism.
For every option, verify the production contract, mint, or asset identifier from an authoritative source and confirm decimals in code. Do not copy a testnet asset into mainnet configuration or assume assets with the same symbol are interchangeable. Add boundary tests around rounding and maximum amounts. The buyer policy should compare both asset identifier and amount, because approving USDC on one network does not authorize a similarly named token elsewhere.
Match facilitator and scheme support
A facilitator supports specific combinations of protocol version, payment scheme, and network. Its presence in an ecosystem list does not prove it supports the exact option returned by a resource. Query or configure supported kinds using the facilitator's documented interface, and fail closed if the route asks it to verify an unregistered combination. If local verification is used, record that architecture rather than implying a remote facilitator settled the payment.
Run verification and settlement tests separately. A facilitator may parse and verify a proof yet fail to submit or confirm settlement because of RPC, liquidity, signer, gas-sponsorship, or network conditions. Capture the transaction reference and final status when available. Avoid automatic cross-network fallback after a signed attempt; a buyer must select and authorize a different requirement deliberately.
| Layer | Required evidence | Common false positive |
|---|---|---|
| Network | Canonical CAIP-2 ID | A chain name in marketing copy |
| Asset | Correct identifier, decimals, and amount | A familiar ticker symbol |
| Facilitator | Scheme and network supported | A generally reachable facilitator URL |
| Delivery | Settled retry returns valid output | Verification succeeded |
Register the correct signer and server implementation
The buyer needs a signer compatible with the selected network family and payment scheme. An EVM account signer cannot create an SVM proof, and package installation alone does not register the handler. Initialize clients with explicit network patterns, keep specific registrations ahead of broad wildcards where the SDK supports them, and test that policy selection does not choose an option the wallet cannot sign.
The resource server needs the corresponding scheme implementation and must encode its challenge using the current transport headers and protocol types. Pin compatible package versions across core, network, framework, and extension modules. A mixed-version dependency graph can compile while encoding different assumptions. Include a protocol-level fixture test in addition to framework middleware tests so failures are not hidden behind routing or serialization.
Separate testnet and mainnet readiness
A successful testnet call proves the integration can traverse one controlled environment. It does not prove the production asset, pay-to destination, facilitator signer, RPC path, or operational policy. Keep separate configuration objects, wallets, secrets, analytics, and evidence records. Require an explicit deployment gate before changing a route from testnet requirements to mainnet requirements.
Build a test matrix for each option: unpaid challenge, policy selection, valid payment, insufficient amount, wrong asset, wrong network, expired requirement, replay, duplicate retry, facilitator timeout, settlement uncertainty, and origin failure after payment. Then perform a low-value mainnet canary with output validation. Record the observation date because network and facilitator support can change after the initial launch.
Publish multi-network support without overstating it
List support at the resource-route level. One provider may accept several networks on one endpoint and only one network on another. Show the CAIP-2 identifier, asset, scheme, price, facilitator dependency, and most recent evidence for each option. If only a quote was observed, label it quote-confirmed. Reserve paid-call verified for a settled call whose response passed the defined output check on that option.
Do not collapse duplicate or inconsistent requirements into a single badge. Normalize display labels while retaining the raw evidence for diagnosis. If one network fails, keep healthy options visible and mark the failed option with its last result and date. Multi-network support should improve buyer choice, not make a listing less precise. The goal is deterministic selection and verifiable delivery, not the largest possible row of logos.
Related directory entries
Sources and methodology
TOLL·402 distinguishes public claims, registry discovery, unpaid quote checks and settled paid-call verification. Sources below support the visible claims; presence in a registry is not treated as verification.
- x402 network and token support — Authoritative x402 network identifiers, default assets, and implementation guidance.
- CAIP-2 blockchain ID specification — Primary chain-agnostic specification for namespace and reference identifiers.
- x402 v1 to v2 migration guide — Authoritative protocol migration details, including CAIP-2 identifiers and split network-family packages.
- x402 protocol repository — Canonical specifications and reference implementations for current network and scheme behavior.