Web3 Beginner Series: Exploring the New On-Chain Payment Protocol — x402

Coinbase recently announced a new payment protocol: x402. As x402 was initiated by Coinbase, it naturally supports Base Sepolia by default. It has also added support for the Solana chain, demonstrating that x402 is not bound to any specific blockchain.

https://github.com/coinbase/x402

To understand the workflow, I created a repository (https://github.com/gin-lsl/x402-solana-demo) containing the complete Server, Client, and Facilitator components. I chose Koa as the base framework to implement a scenario where a client pays with Devnet USDC (a custom token) to access a specific API endpoint provided by the server.

Some explanations

I used the spl-token tool to create the token, visible here:
https://solscan.io/token/9gKBTRXgVTszU31A12oJKKSy6aje8LyoVvNfSimembHo?cluster=devnet

Solana was selected for its developer-friendly environment, offering near-unlimited test tokens for development and testing—no login, social account binding, or mainnet wallet balance required.

Running the Project:

1. Create a .env file with required environment variables.
2. Execute the following commands:

# Run Server (and Facilitator)
pnpm dev

# Run client
pnpm pay:fetch

Code Explanation

The demo consolidates all components for simplicity. Key files:

1. solana.ts

• Provides a /solana/get-balance endpoint (a "valuable" API requiring payment).
• Acts as the Server, handling business logic (steps 5–8 in the sequence diagram, specifically step 7).
• Allows Web2 developers to integrate Web3 payments without deep blockchain knowledge.

2. facilitator.ts

• Implements the Facilitator with /supported, /verify, and /settle endpoints for chain support checks, transaction validation, and on-chain settlement.
• Requires a private key to cover transaction fees (steps 9–10 in the diagram).
• Standardized; can use official templates. Adaptation needed for non-Base chains:

• For unsupported chains (e.g., Solana), simulate transactions for verification.
• Uses @solana/kit to send transactions via RPC (sendTransaction) and confirm results (waitForRecentTransactionConfirmation).

3. x402-middleware.ts

• Koa middleware linking Server and Facilitator.
• Guards paid endpoints, returns HTTP 402, and routes /verify//settle requests.
• Demo simplifications:

• maxAmountRequired set artificially high to avoid client-side validation errors.
• asset uses a custom Devnet token (not x402’s default). On mainnet, this should be official USDC.

• Unlike Express (which overrides Response for an onion model), Koa natively supports the flow: verify → business logic → settle.

4. payment-client-fetch.ts

• Client role (steps 1–4). Uses x402-fetch helpers to:

• Auto-handle 402 responses.
• Sign transactions with the wallet’s private key.
• Resend requests with the X-PAYMENT header.

• Flow: Direct API call → 402 response → signature generation → retry with signed payload.

Run Commands:

# Run Server
pnpm dev

# Run client
pnpm client

Client logs/output:

> pnpm run --parallel client

server client$ tsx src/payment-client-fetch.ts
server client: [dotenv@17.2.3] injecting env (4) from .env -- tip: 🔄 add secrets lifecycle management: https://dotenvx.com/ops
server client: headers: Headers {
server client:   vary: 'Origin',
server client:   'access-control-allow-origin': '*',
server client:   'content-type': 'application/json; charset=utf-8',
server client:   'content-length': '399',
server client:   date: 'Fri, 31 Oct 2025 16:16:10 GMT',
server client:   connection: 'keep-alive',
server client:   'keep-alive': 'timeout=5'
server client: }
server client: body: {
server client:   "success": true,
server client:   "data": {
server client:     "address": "8dQE449ozUAS2XPyvao6hEpkAtGALo1A1q4TApayFfCo",
server client:     "balance": {
server client:       "lamports": "14095638085",
server client:       "sol": "14.095638085"
server client:     }
server client:   },
server client:   "paymentInfo": {
server client:     "amount": 0.1,
server client:     "currency": "SOL",
server client:     "settled": {
server client:       "success": true,
server client:       "payer": "8jDsKhqYn15fhpMXMFcZJMZVkzDMAVvUgh29y2ws9iJi",
server client:       "transaction": "5GJDV8AugQFJqWJYmgkmUebyYvhcZZNEq3XQ1MunXKamtgFwo7HvdjZFq55FJ77AF1gDXnJ6ogSDx27VWmPeSo5r",
server client:       "network": "solana-devnet"
server client:     }
server client:   }
server client: }
server client: no x-payment-response header, status: 200
server client: Done

Reflections

If earlier Web3 efforts focused on user accessibility (payments, investments), x402 targets Web2 developers by lowering barriers to Web3 payment integration.

While x402/client helpers streamline user payments (e.g., via USDC wallets), the protocol’s greater impact lies in empowering service providers.

Challenges for adoption:

• Enterprises with legacy settlement systems may resist due to integration complexity and regulatory concerns.
• Node RPC providers could leverage x402 to monetize advanced APIs (e.g., transaction acceleration).

Final Note:
x402 is a foundational standard, not a solution. Its value lies in unifying ecosystems around a shared specification. Rational evaluation is crucial—avoid hype traps.