x402 Server / Merchant Integration

Overview

As an x402 merchant, your server advertises payment requirements on protected routes. When a client makes a request to a paid endpoint, the server responds with an HTTP 402 Payment Required status along with payment details -- including the price, accepted network, and facilitator URL. The client then constructs and signs a payment transaction, resubmitting the request with a payment header. Your server forwards this payment to the facilitator, which handles verification and settlement on your behalf.

This architecture keeps your server logic simple: you define which routes cost money and how much, and the facilitator takes care of validating cryptographic proofs, settling funds to your wallet, and returning confirmation to your server so it can serve the protected resource.

How It Works

1. Define paid routes -- Annotate or configure specific endpoints with a price, network, and description.
2. Client receives 402 -- When a client hits a paid route without a valid payment header, your server returns 402 Payment Required with a JSON body describing the payment terms.
3. Client pays -- The client constructs a Solana transaction fulfilling the payment requirements and resends the request with an X-PAYMENT header.
4. Facilitator verifies and settles -- Your server forwards the payment proof to the facilitator at https://facilitator.svmacc.tech. The facilitator verifies the transaction on-chain and settles funds to your wallet address.
5. Server responds -- Once payment is confirmed, your server returns the protected resource as normal.

Supported Frameworks

x402 provides first-class middleware integrations for popular web frameworks across multiple languages.

TypeScript / JavaScript

Framework	Package
Express.js	x402-express
Hono	x402-hono

Python

Framework	Package
FastAPI	x402
Flask	x402

Prerequisites

Before integrating x402 into your server, make sure you have:

• A Solana wallet address to receive payments.
• Access to the facilitator service at https://facilitator.svmacc.tech.
• A target network (e.g., solana-devnet for testing, solana-mainnet for production).

Next Steps

Choose the guide for your preferred framework above to get started with a working example in minutes.