API Reference

x402‑compatible endpoints for quote → pay → retry flows. JSON first, USDC on Base, proof via X‑PAYMENT header.

POST/api/x402/pay

Request payment quote or process payment proof. Returns HTTP 402 when payment is required.

Request

Body:
{
  "serviceId": "string (required)",
  "amount": "string (optional)",
  "proof": "object (optional)"
}

Responses

  • 200:Success - Payment verified, service fulfilled
  • 402:Payment Required - Contains payment quote
POST/api/x402/verify

Verify payment proof with PayAI facilitator. Supports X-PAYMENT header (x402 spec).

Request

Body:
{
  "proof": "object (required)",
  "settle": "boolean (optional)"
}
Headers:
{
  "X-PAYMENT": "string (optional) - JSON-encoded payment proof"
}

Responses

  • 200:Verification result with settlement details
GET/api/marketplace/services

List available x402 services from database. Supports filtering by category and merchant.

Request

Query Parameters:
{
  "category": "string (optional)",
  "merchant": "string (optional)",
  "network": "string (optional, default: base)",
  "chainId": "number (optional, default: 8453)"
}

Responses

  • 200:List of services with metadata
POST/api/sync/payai

Sync services from PayAI facilitator to database. Can be called manually or via cron.

Request

Headers:
{
  "Authorization": "Bearer YOUR_SYNC_SECRET (optional)"
}

Responses

  • 200:Sync result with counts
GET/api/panel/user/stats

Get user statistics and summary. Requires wallet address authentication.

Request

Query Parameters:
{
  "address": "string (required) - User wallet address"
}

Responses

  • 200:User stats with transaction summary
GET/api/panel/platform/analytics

Get platform-wide analytics. Admin-only access.

Request

Query Parameters:
{
  "period": "string (optional) - 7d, 30d, 90d, all"
}

Responses

  • 200:Platform analytics and metrics

Example: Payment Flow

Complete example of requesting a payment quote and processing payment:

Payment Flow Example
// 1. Request payment quote
const quoteResponse = await fetch('/api/x402/pay', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    serviceId: 'claude-sonnet-api',
    amount: '0.25',
  }),
});

// 2. Handle 402 Payment Required
if (quoteResponse.status === 402) {
  const { payment } = await quoteResponse.json();
  // payment.amount: "$0.25"
  // payment.amountRaw: "250000" (in smallest unit, 6 decimals)
  // payment.token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  // payment.merchant: "0x..."
  // payment.deadline: 1234567890
  // payment.nonce: "unique-nonce"
  
  // 3. Approve payment in wallet
  const txHash = await transferUSDC(wallet, payment.merchant, payment.amountRaw);
  
  // 4. Retry with payment proof
  const successResponse = await fetch('/api/x402/pay', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-PAYMENT': JSON.stringify({
        transactionHash: txHash,
        from: wallet.address,
        to: payment.merchant,
        amount: payment.amountRaw,
        token: payment.token,
      }),
    },
    body: JSON.stringify({
      serviceId: 'claude-sonnet-api',
      proof: {
        transactionHash: txHash,
        from: wallet.address,
        to: payment.merchant,
        amount: payment.amountRaw,
        token: payment.token,
      },
    }),
  });
  
  // 5. Access granted
  const result = await successResponse.json();
}
X-PAYMENT Header
The X-PAYMENT header follows the x402 specification. You can send payment proof either in the header or request body. Header takes precedence if both are provided.

Base URL

All API endpoints are relative to your deployment URL. For local development:

# Local development
http://localhost:3000/api/...

# Production
https://your-domain.vercel.app/api/...
server.r1xlabs.com