Protect an Endpoint

Full guide to adding x402 payment gating to any HTTP endpoint — covering middleware options, price configuration, multi-route setup, and body validation for POST endpoints.

Supported Frameworks

Framework	Package
Express	`@x402/express`
Fetch-compatible (Node, Deno, Bun)	`@x402/fetch`
Next.js / Edge	`@x402/next`

Express — Full Configuration

import { paymentMiddleware, x402ResourceServer } from '@x402/express';
import { ExactSvmScheme } from '@x402/svm/exact/server';
import { HTTPFacilitatorClient } from '@x402/core/server';
 
const facilitator = new HTTPFacilitatorClient({
  url: 'https://x402.agentstrail.ai',
});
 
const resourceServer = new x402ResourceServer(facilitator)
  .register('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', new ExactSvmScheme())   // mainnet
  .register('solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', new ExactSvmScheme());  // devnet
 
app.use(paymentMiddleware({
 
  // Simple GET route
  'GET /price': {
    accepts: [{
      scheme:  'exact',
      price:   '$0.01',
      network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
      payTo:   process.env.MY_WALLET,
      asset:   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
    }],
  },
 
  // POST route with higher price
  'POST /analysis': {
    accepts: [{
      scheme:  'exact',
      price:   '$0.10',
      network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
      payTo:   process.env.MY_WALLET,
      asset:   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
    }],
  },
 
}, resourceServer));

Wildcard Routes

Use * to protect all routes under a path:

'GET /api/*': {
  accepts: [{ ... }],
}

Discovery Metadata

Clients discover your endpoint's price via the X-Payment-Required response header returned on the initial 402. For Orchus Library listing, also register on the onboarding page so your metadata (name, description, tags) is indexed.

Testing Your Endpoint

After adding middleware, verify the 402 response:

curl -i https://yourapi.com/price
# HTTP/1.1 402 Payment Required
# X-Payment-Required: [{"scheme":"exact","network":"solana:5eykt4...","maxAmountRequired":"10000",...}]

Then test paying with the Orchus MCP probe:

{ "tool": "orchus_probe", "arguments": { "url": "https://yourapi.com/price" } }