SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsx402-facilitator

x402-facilitator

Coding & development

View repository

Updated 10-16 00:24

About this skill

x402 Integration Guide

This skill helps LLM developers integrate on-chain payments into their applications using the x402 protocol and the facilitator packages.

What x402 Does

x402 revives the HTTP 402 Payment Required status code. Instead of API keys or subscriptions, a server returns 402 with payment requirements (amount, token, recipient). The client signs an off-chain authorization and re-sends the request with payment attached. A facilitator (relayer) verifies the signature and submits the on-chain transaction — the buyer never needs ETH for gas.

The key insight: payments happen at the HTTP layer. No accounts, no OAuth, no billing portal. Just: request → 402 → pay → 200.

Two Integration Scenarios

1. You have an API and want to charge per request (Seller)

Your server returns 402 when a request arrives without payment, then verifies and settles the payment before delivering the resource. You can use the official @x402/express (or @x402/hono, @x402/next) middleware for automatic handling, or implement the 402 flow manually for full control.

Read references/building-a-seller.md for the complete flow with code examples.

2. You have an agent that pays other agents/services (Buyer)

Your client wraps fetch with @x402/fetch so 402 responses are handled automatically — the client signs the payment and re-sends the request transparently. For EIP-7702 payments (any ERC-20 or native ETH), you provide a SchemeNetworkClient implementation that signs EIP-712 intents and EIP-7702 authorizations using viem.

Read references/building-a-buyer.md for the complete client setup with code examples.

Choose Your Payment Mechanism

Mechanism Scheme Tokens When to Use
EIP-7702 eip7702 Any ERC-20 (USDT, DAI) + native ETH You want to accept any token, or sell for ETH
ERC-3009 exact USDC and tokens with transferWithAuthorization You only need USDC — simplest setup

Both mechanisms are gasless for the buyer. The facilitator pays gas and submits the on-chain transaction.

If you want to accept USDC and USDT, register both schemes — the seller lists both in its accepts array and the buyer picks one based on their token balance.

Self-Hosted Facilitator vs Public Facilitator

Public facilitators like Coinbase CDP (https://api.cdp.coinbase.com/platform/v2/x402) support the exact scheme (ERC-3009/USDC) out of the box. If that's all you need, you don't need @facilitator/server.

You need the self-hosted facilitator when:

  • You want to accept any ERC-20 token (USDT, DAI, custom tokens) via EIP-7702
  • You want to accept native ETH payments
  • You want persistent nonce tracking and settlement audit trails (database-backed)
  • You want full control over the relayer, delegate contract, and verification logic

Read references/facilitator-server.md for setup instructions, CLI options, database configuration, and the full HTTP API reference.

Deployed Delegate Contract

The EIP-7702 mechanism relies on a Delegate.sol smart contract that is deployed at the same address on all major EVM networks via CREATE2:

Network Chain ID Address
Ethereum 1 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd
Optimism 10 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd
BNB Chain 56 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd
Polygon 137 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd
Base 8453 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd
Arbitrum 42161 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd
Avalanche 43114 0xD064939e706dC03699dB7Fe58bB0553afDF39fDd

For chains not listed here, deploy the contract yourself. Read references/delegate-contract.md for deployment instructions and contract details.

Integration Checklist

When helping a developer integrate, walk through these steps in order:

Step 1: Determine the scenario

  • Are they building a seller (accepting payments for an API/resource)?
  • Are they building a buyer (an agent that pays for resources)?
  • Or both (agent-to-agent)?

Step 2: Choose the payment mechanism

  • USDC only → exact scheme (ERC-3009), can use public facilitator
  • Any ERC-20 or ETH → eip7702 scheme (EIP-7702), needs self-hosted facilitator
  • Both → register both schemes

Step 3: Verify the Delegate contract is deployed on their target chain

  • Check the table above for known networks
  • If not listed, guide them through deploying via Foundry (see references/delegate-contract.md)

Step 4: Set up the facilitator (if using EIP-7702)

  • Install and run @facilitator/server pointing to their chain RPC
  • Fund the relayer wallet with ETH for gas
  • Configure database for production (see references/facilitator-server.md)

Step 5: Implement the seller side (if applicable)

  • Add 402 response logic or use @x402/express middleware
  • Define payment requirements (scheme, network, asset, amount, payTo)
  • Wire verify + settle calls to the facilitator
  • See references/building-a-seller.md for full code

Step 6: Implement the buyer side (if applicable)

  • Install @x402/fetch and viem
  • Implement SchemeNetworkClient for EIP-7702 (or use ExactEvmScheme from @x402/evm for ERC-3009)
  • Wrap fetch with wrapFetchWithPaymentFromConfig
  • See references/building-a-buyer.md for full code

Step 7: Test end-to-end

  • Verify the buyer can receive a 402 response, sign payment, and get the resource
  • Check the facilitator logs for verification and settlement details
  • Verify on-chain that the token transfer completed

Quick Reference: EIP-712 Domain

The Delegate contract uses this EIP-712 domain for signing payment intents:

const domain = {
  name: "Delegate",
  version: "1.0",
  chainId: <chainId>,
  verifyingContract: <buyer's EOA address>,  // not the delegate contract!
};

The verifyingContract is the buyer's own address because under EIP-7702, the delegate code runs as the buyer's account — so the EIP-712 domain must use the buyer's address as the verifying contract.

Common Pitfalls

  • Viem signAuthorization field mapping: Depending on the viem version, signAuthorization might return address instead of contractAddress, or v instead of yParity. The facilitator expects contractAddress and yParity. Always map these safely: contractAddress: auth.contractAddress ?? auth.address.
  • No ERC-20 approve() needed: Under EIP-7702, the Delegate contract runs in the context of the buyer's account and calls transfer directly (not transferFrom). The buyer does not need to approve the Delegate contract to spend their tokens.
  • Wrong verifyingContract: The EIP-712 domain's verifyingContract must be the buyer's EOA address, NOT the Delegate contract address. This is the #1 source of InvalidSignature errors.
  • Testing Expiration returns InvalidSignature: If you manually modify an intent's deadline after it's been signed to test the expiration logic, the signature will fail to recover correctly, resulting in an InvalidSignature error rather than Expired.
  • ETH payments need the zero address: For native ETH payments, set asset to 0x0000000000000000000000000000000000000000 and use EthPaymentIntent. Note: While token is omitted, the amount, to, nonce, and deadline fields are still required.
  • Anvil testing requires Prague: If testing locally on Anvil, you must start Anvil with --hardfork prague. Without it, EIP-7702 Type 4 transactions will fail to persist delegation code.
  • Missing extra fields for ERC-3009: The exact scheme requires extra.name and extra.version matching the target USDC contract's EIP-712 domain.
  • Relayer needs ETH: The self-hosted facilitator's relayer pays gas for every settlement. Monitor the /info endpoint for balances.