x402 Paywall Setup: Protect API Endpoints with USDC

The FlareHQ x402 middleware sits in front of your existing route handler and enforces a USDC micro-payment before any request reaches your application logic. When a client arrives without a valid payment proof, the middleware returns HTTP 402 Payment Required with machine-readable pricing details. When the proof is present and valid, the middleware lets the request through transparently — your handler code never changes.

Middleware Configuration

The createX402Middleware function accepts three required parameters and one optional one:

string

required

The amount to charge per request, denominated in USDC (e.g., "0.001" for one-tenth of a cent).

string

required

The wallet address that receives USDC settlement. This is typically your treasury or operator wallet on Arc testnet.

number

required

The chain to settle on. For Arc testnet this is always 5042002.

boolean

When true, the middleware rejects requests that do not include a valid X-Agent-ID header. Useful if you want to restrict your endpoint to identified ERC-8004 agents only. Defaults to false.

Express / Node.js Setup

Installing the middleware in Express takes a single app.use call. Mount it on the path you want to protect:

Install the FlareHQ SDK

npm install @flarehq/sdk

Add the middleware to your route

import express from 'express';
import { createX402Middleware } from '@flarehq/sdk';

const app = express();

app.use(
  '/api/v1/premium-data',
  createX402Middleware({
    priceUsdc: '0.001',
    payTo: '0x3500000000000000000000000000000000008004',
    chainId: 5042002,
  })
);

// Your handler only runs after payment is verified
app.get('/api/v1/premium-data', (req, res) => {
  res.json({ data: 'Your premium payload here' });
});

app.listen(3000);

You can mount createX402Middleware on any path prefix, which means you can gate an entire namespace — for example, app.use('/api/v1/premium', ...) — with a single line.

Next.js API Route Setup

Next.js API routes don’t use Express middleware, so you verify the payment proof manually using the flarehq.x402.verifyPaymentProof method:

// app/api/v1/premium-data/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { FlareHQ } from '@flarehq/sdk';

const flarehq = new FlareHQ({ apiKey: process.env.FLAREHQ_SECRET_KEY! });

export async function GET(req: NextRequest) {
  const x402Proof = req.headers.get('X-402-Payment-Proof');

  // Step 1: Return 402 if no proof is present
  if (!x402Proof) {
    return NextResponse.json(
      {
        error: 'Payment Required',
        x402: {
          price: '0.001',
          asset: 'USDC',
          payTo: process.env.TREASURY_ADDRESS,
          chainId: 5042002,
        },
      },
      { status: 402 }
    );
  }

  // Step 2: Validate the proof cryptographically
  const isValid = await flarehq.x402.verifyPaymentProof(x402Proof);
  if (!isValid) {
    return NextResponse.json(
      { error: 'Invalid Payment Proof' },
      { status: 403 }
    );
  }

  // Step 3: Proof is valid — serve your data
  return NextResponse.json({ data: 'Your premium payload here' });
}

verifyPaymentProof performs on-chain verification against Arc testnet. The call is fast (typically under 200 ms) because Arc uses Circle’s Gateway API rather than scanning full block history.

What the 402 Response Looks Like

When a client hits your paywall without a valid proof, they receive a structured JSON body alongside the 402 status code:

{
  "error": "Payment Required",
  "x402": {
    "price": "0.001",
    "asset": "USDC",
    "payTo": "0x3500000000000000000000000000000000008004",
    "chainId": 5042002
  }
}

Clients that implement x402 — including the FlareHQ SDK and any x402 Marketplace consumer — parse this body automatically, sign a Circle Nanopayment authorization, and retry the request with the X-402-Payment-Proof header attached.

Testing Your Paywall

You can confirm your paywall is working correctly with a plain cURL request. You should receive a 402 response with the pricing body:

curl -i https://your-api.example.com/api/v1/premium-data

Expected output:

HTTP/2 402
content-type: application/json

{
  "error": "Payment Required",
  "x402": {
    "price": "0.001",
    "asset": "USDC",
    "payTo": "0x3500000000000000000000000000000000008004",
    "chainId": 5042002
  }
}

To test a successful paid request, use the FlareHQ SDK or submit directly to POST /api/x402/pay with a valid payment proof:

curl -X POST https://flarehq.xyz/api/x402/pay \
  -H "Authorization: Bearer fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -H "X-402-Payment-Proof: 0x402_proof_..." \
  -d '{
    "slug": "your-listing-slug",
    "method": "GET",
    "params": {},
    "agentId": "8004:5042002:1042"
  }'

Plain HTTP clients — such as raw fetch calls or cURL without special headers — will always receive a 402 and must implement their own x402 payment logic to proceed. Only clients using the FlareHQ SDK, the x402 Marketplace executor, or a compatible x402 library can pay automatically.

Restricting to Identified Agents Only

If you want your endpoint to accept requests only from ERC-8004 identified agents (and reject anonymous callers), set requireAgentId: true in the middleware config:

app.use(
  '/api/v1/agent-only',
  createX402Middleware({
    priceUsdc: '0.002',
    payTo: process.env.TREASURY_ADDRESS!,
    chainId: 5042002,
    requireAgentId: true, // rejects requests without X-Agent-ID
  })
);

Requests without a valid X-Agent-ID header will receive a 401 Unauthorized response before the payment check even runs.

Get Started

Payments

x402 Protocol

Agentic Finance

Developer Guide

x402 Paywall Setup: Protect API Endpoints with USDC

Middleware Configuration

Express / Node.js Setup

Next.js API Route Setup

What the 402 Response Looks Like

Testing Your Paywall

Restricting to Identified Agents Only

​Middleware Configuration

​Express / Node.js Setup

​Next.js API Route Setup

​What the 402 Response Looks Like

​Testing Your Paywall

​Restricting to Identified Agents Only

Middleware Configuration

Express / Node.js Setup

Next.js API Route Setup

What the 402 Response Looks Like

Testing Your Paywall

Restricting to Identified Agents Only