Skip to main content
Common problems and questions when running x402 on Fireblocks, covering both the facilitator (selling) and the agent (buying). For exact message shapes and error codes, see the Protocol Reference.

​
Facilitator issues

The server refuses to boot, citing mainnet. A configured asset is a mainnet asset and the testnet-only policy is in force. Use a testnet asset, or opt in deliberately with X402_ALLOW_MAINNET=true. The error lists the offending assets. See Network policy. Payments reach settling and never complete. The settlement CONTRACT_CALL is waiting for manual approval in the Fireblocks Console. Add a Policy rule that auto-approves the CONTRACT_CALL from your receiver vault using the network’s gas asset. See Set Policies. To reconcile rows that are already stuck, run x402 payments sync <paymentId> or x402 payments sync-all. An asset I imported does not appear in the 402 quote. The asset cannot be priced. Mark stablecoins stable: true, or give other assets a price_symbol. Unpriceable assets are dropped from the response rather than rejected, so other assets stay available. See PriceProvider. A payment is rejected with unsupported_scheme. The resolved transfer mechanism is not in the product’s pricing rows, or the request did not originate through /api/payments/create and is missing extra.productId. Offer the mechanism on the product, or route the quote through create. See Picking a mechanism. A settlement failed but the funds may have moved. Once a Fireblocks transaction ID is attached to a payment, the facilitator does not force the row to failed on a transient error, because the transaction may still land. Let the reconciler decide from Fireblocks’s own state, or run x402 payments sync <paymentId>. See Inspecting payments.

​
Agent issues

no supported payment mechanism in accepts[]. The server only offered a mechanism the agent cannot sign, such as ERC-7710. Ensure the server offers eip-3009 or permit2. The agent does not sign ERC-7710, because Fireblocks cannot sign delegation payloads. ERROR_TYPED_MESSAGE_TO_PROTECTED_7702_CONTRACT. A Fireblocks Policy rule blocked the signature. Add a typed-message Policy rule that allows this typed data for the agent’s vault. See Set Policies. integrity check failed. The Payment Instruction Integrity envelope expired, the did:web document was unreachable, or the signature did not verify. Check the facilitator’s clock skew and that the DID document is served, or relax to VERIFY_INTEGRITY if you are not enforcing integrity. See Payment Instruction Integrity. Payment expired. Too much time passed between the 402 and the signed retry. Re-request to get a fresh quote, and reduce signing latency. Settlement quotes are valid for maxTimeoutSeconds. Invalid signature. The EIP-712 domain did not match. Verify the name and version in the quote’s extra, and that the chain ID matches the asset’s network. The agent will not pay, reporting insufficient balance. The vault is short of the spend asset. Fund it (see Fund and Control Agent Spending), or, only for testing, disable the check with check_balance: false.

​
Frequently asked questions

Does my customer traffic pass through the facilitator? No. Your server serves its own traffic and returns the 402 itself. It calls the facilitator only to verify and settle. The facilitator is API-only. Who pays the on-chain gas? The facilitator’s vault pays settlement gas. The payer signs off-chain and spends no gas at signing time, except for a one-time setup transaction the first time it uses Permit2 or ERC-7710. Can I accept tokens other than USDC? Yes. USDC uses the eip-3009 mechanism; any other ERC-20 settles through the permit2 or upto-permit2 mechanisms. See Transfer mechanisms. Can I charge a variable amount? Yes, with the upto scheme and the upto-permit2 mechanism, where the payer signs a ceiling and the facilitator settles up to it. Your pricing logic is responsible for staying within the signed maximum. Do I have to run the facilitator myself? No. Fireblocks offers a managed, hosted facilitator with the same payment model. See Get Started with x402 or talk to us about early access. How do I limit what an agent can spend? Spending limits live in Fireblocks Policy rules (per-transaction caps, velocity caps, destination allowlists, approval thresholds), not in the agent code. See Fund and Control Agent Spending. Is mainnet supported? Yes, but it is off by default. The facilitator is testnet-only until you set X402_ALLOW_MAINNET=true. Review the operator responsibilities first. See Network policy.