Skip to main content

What is x402?

x402 is an HTTP payment protocol that enables gasless, signature-based payments to authenticate API requests. Instead of on-chain transactions, users sign an EIP-712 message that authorizes a payment facilitator to transfer tokens on their behalf. Key benefits:
  • โœ… No gas fees for users
  • โœ… Instant payment verification
  • โœ… Works over standard HTTP
  • โœ… Perfect for API monetization

Why Combine Them?

Many facilitators only accept specific tokens on specific chains. In addition, x402 requires EIP-3009 on the token contract further limiting token support. However, Trails enables x402 using any token from any chain. Trails + x402 creates a powerful payment flow:
  1. User pays with Trails using any token from any chain
  2. Payment arrives on your chosen chain and token that the facilitator supports (e.g., Base USDC)
  3. Automatic trigger of x402 signature for API access
  4. Gasless authentication to your protected endpoints
  5. API responds with paid content/service

Architecture

Implementation

Frontend Setup

1. Install Dependencies

This example pairs Trails with an existing wagmi + RainbowKit setup. Since 0xtrails@0.16.0, wagmi is opt-in for Trails โ€” also install @0xtrails/adapter-wagmi so Trails can share the wagmi session:

2. Configure Providers

3. Create x402 API Client

The withPaymentInterceptor automatically handles EIP-712 signature creation and attaches payment headers to HTTP requests.

4. Build Payment Widget Component

The onPaymentSuccess callback is the bridge between Trails and x402. It fires when the cross-chain payment succeeds, then triggers the x402 signature flow.

Backend Setup

1. Install Dependencies

2. Configure Environment

3. Create x402 Protected API

The paymentMiddleware intercepts requests to protected routes and verifies the x402 payment signature before allowing access.

Payment Flow Breakdown

Step 1: User Initiates Payment (Trails)

The user clicks the Trails button and:
  • Selects their source chain and token (e.g., ETH on Arbitrum)
  • Trails calculates optimal route (swap โ†’ bridge โ†’ execute)
  • User approves transaction
  • Payment arrives as USDC on Base
Trails handles all complexity: token swaps, bridge routing, gas estimation, and delivery confirmation.

Step 2: Trails Callback Triggers x402

When onPaymentSuccess fires:
  1. API client is configured with the userโ€™s wallet
  2. HTTP request is made to protected endpoint
  3. x402 interceptor prompts for EIP-712 signature
  4. Signature is attached to request headers

Step 3: x402 Signature Creation

The interceptor:
  1. Detects 402 Payment Required response
  2. Parses payment details from response headers
  3. Creates EIP-712 typed data structure
  4. Prompts user to sign (gasless, off-chain)
  5. Retries request with payment signature
Users sign a message, not a transaction. This is gasless and instant.

Step 4: Backend Verification

The middleware:
  1. Validates payment signature
  2. Sends transfer request to facilitator
  3. Facilitator transfers tokens from user โ†’ your wallet
  4. If successful, request proceeds to handler
  5. If failed, returns 402 Payment Required

Step 5: Protected Response

Only accessible if payment succeeds.

Conclusion

Combining Trails and x402 creates a seamless payment experience:
  • Trails handles the complexity of cross-chain payments
  • x402 provides gasless, instant API authentication
  • Together they enable truly user-friendly paid services - paid with any token from any chain.
This pattern works for:
  • ๐Ÿ” API monetization
  • ๐Ÿ“ฐ Content paywalls
  • ๐ŸŽฎ Gaming microtransactions
  • ๐Ÿ“Š Data services
  • ๐Ÿค– AI API access
  • ๐Ÿ’ผ SaaS applications
Start building payment-gated services today!