API Reference

Complete API reference for x402 libraries, middleware, and facilitator endpoints.

Express Middleware

paymentMiddleware()

Creates Express middleware for x402 payment protection.

Parameters

payTostring | Record<string, string>

Wallet address(es) to receive payments

routesRecord<string, RouteConfig>

Route configurations with pricing

optionsMiddlewareOptions

Facilitator URL and other settings

Example

app.use(
  paymentMiddleware(
    "0x742d35Cc6634C0532925a3b844Bc9e7595f0bFa0",
    {
      "GET /api/data": {
        price: "$0.001",
        network: "base"
      },
      "/premium/*": {
        price: "$0.01",
        network: "base"
      }
    },
    {
      url: "https://facilitator.payai.network",
      timeout: 5000
    }
  )
);

Python Decorators

@require_payment()

Decorator to protect endpoints with x402 payments.

Parameters

pricestr | Callable

Price as dollar string or function

networkstr

Blockchain network (base, polygon, solana)

Example

@app.get("/data")
@require_payment(price="$0.001", network="base")
async def get_data():
    return {"data": "premium content"}

# Dynamic pricing
@app.post("/generate")
@require_payment(
    price=lambda req: "$0.05" if len(req.body) > 1000 else "$0.01",
    network="base"
)
async def generate(request):
    return {"result": "generated content"}

Client Library

X402Client

Client for consuming x402-protected services.

Constructor

new X402Client(options: X402ClientOptions)

Options

signerSigner

Ethers.js signer or wallet instance

networkstring

Network to use for payments

maxPaymentstring (optional)

Maximum payment per request

autoApproveboolean (optional)

Auto-approve payments (default: true)

Methods

get(url, options?)

Make GET request with automatic payment

post(url, options?)

Make POST request with automatic payment

put(url, options?)

Make PUT request with automatic payment

delete(url, options?)

Make DELETE request with automatic payment

Facilitator API

POST /verify

Verify a blockchain transaction for x402 payment.

Request

POST https://facilitator.payai.network/verify
Content-Type: application/json

{
  "txHash": "0x5f2d8a...",
  "network": "base",
  "expectedAmount": "1000000",
  "expectedRecipient": "0x742d35Cc...",
  "tokenAddress": "0x833589fCD6..." // Optional
}

Response

{
  "valid": true,
  "confirmed": true,
  "amount": "1000000",
  "recipient": "0x742d35Cc...",
  "sender": "0x123...",
  "timestamp": 1704067200,
  "blockNumber": 12345678
}

HTTP Headers

X-Accept-Payment

Server indicates payment is required

X-Accept-Payment: pay.base 0.001 USDC

X-Payment-Address

Wallet address to send payment to

X-Payment-Address: 0x742d35Cc6634C0532925a3b8...

X-Payment-Network

Blockchain network for payment

X-Payment-Network: base

X-Payment-Proof

Client provides transaction hash as proof

X-Payment-Proof: 0x5f2d8a...

X-Facilitator-URL

URL for payment verification

X-Facilitator-URL: https://facilitator.payai.network

Need Help?

Check out code examples or visit the full PayAI documentation.

Code Examples PayAI Docs