@x402-checkpoint/nextjs

Zero-config x402 payment integration for Next.js API routes.

Installation

npm install @x402-checkpoint/nextjs

Quick Start

Wrap any route handler to require payment:

// app/api/premium/route.ts
import { withCheckPoint } from '@x402-checkpoint/nextjs';

async function handler(req: Request, { x402 }) {
  console.log('Paid by:', x402.payer);
  console.log('TX Hash:', x402.txHash);
  
  return Response.json({ 
    data: 'premium content',
    paidBy: x402.payer 
  });
}

export const GET = withCheckPoint(handler, {
  price: '0.01 USDC',
  recipient: '0xYourWalletAddress'
});

How It Works

1. No payment? → Returns 402 with payment requirements
2. Invalid payment? → Returns 402 with error details
3. Valid payment? → Verifies, settles, then runs your handler

Configuration

withCheckPoint(handler, {
  // Required
  price: '0.01 USDC',           // Human-readable or raw units '10000'
  recipient: '0xYour...',        // Your wallet address
  
  // Optional
  network: 'eip155:8453',        // Base Mainnet (default)
  maxTimeout: 3600,              // Authorization timeout (default: 1 hour)
  description: 'Premium API',    // Resource description
  facilitatorUrl: 'https://...'  // Custom CheckPoint instance
});

Networks

| Network | ID | |---------|-----| | Base Mainnet | eip155:8453 | | Base Sepolia | eip155:84532 |

Payment Flow

Client                    Your API                  CheckPoint
  |                          |                          |
  |-- GET /api/premium ----->|                          |
  |<---- 402 + requirements --|                          |
  |                          |                          |
  |-- Sign EIP-712 --------->|                          |
  |                          |                          |
  |-- GET + X-Payment ------>|                          |
  |                          |-- POST /verify --------->|
  |                          |<---- { valid: true } ----|
  |                          |-- POST /settle --------->|
  |                          |<---- { txHash: 0x... } --|
  |<---- 200 premium data ---|                          |

X402 Context

Your handler receives payment context:

interface X402Context {
  payer: string;    // Wallet that paid
  amount: string;   // USDC amount (raw units)
  txHash?: string;  // Settlement transaction hash
}

Manual Requirements

For custom flows, create requirements without the wrapper:

import { createPaymentRequirements, parsePrice } from '@x402-checkpoint/nextjs';

export async function GET(req: Request) {
  const requirements = createPaymentRequirements({
    price: '0.01 USDC',
    recipient: '0x...',
  }, req.url);
  
  return new Response(JSON.stringify(requirements), { status: 402 });
}

License

MIT