x402-seller-sdk

JWT proof verification SDK for x402 sellers. Verify payment proofs using JWKS (JSON Web Key Set) with automatic key rotation support.

Installation

npm install x402-seller-sdk

Quick Start

import { SellerSDK } from 'x402-seller-sdk';

const sdk = new SellerSDK({
  jwksUrl: process.env.X402_JWKS_URL!,
  issuer: process.env.X402_EXPECTED_ISS,
  audience: process.env.X402_EXPECTED_AUD,
});

// Verify a payment proof
try {
  const proof = await sdk.verifyProof(token, '/api/today');
  console.log('Payment verified:', proof);
} catch (error) {
  console.error('Verification failed:', error.message);
}

Environment Variables

X402_JWKS_URL="https://gateway.x402.org/.well-known/jwks.json"
X402_EXPECTED_ISS="x402-gateway"
X402_EXPECTED_AUD="your-project-id"

Next.js Middleware Example

import { NextRequest, NextResponse } from 'next/server';
import { SellerSDK, encodeVerifiedPayload } from '@x402/seller-sdk';

const sdk = new SellerSDK({
  jwksUrl: process.env.X402_JWKS_URL!,
  issuer: process.env.X402_EXPECTED_ISS,
  audience: process.env.X402_EXPECTED_AUD,
});

export async function middleware(req: NextRequest) {
  const url = new URL(req.url);

  // Protect specific routes
  if (url.pathname === '/api/today') {
    const token = SellerSDK.extractProof(req.headers, req.cookies);

    if (!token) {
      return new NextResponse(JSON.stringify({ error: 'Payment required' }), {
        status: 402,
        headers: { 'Content-Type': 'application/json' },
      });
    }

    try {
      const verified = await sdk.verifyProof(token, '/api/today');

      // Inject verified payload for downstream use
      const res = NextResponse.next();
      res.headers.set('x-verified-payload', encodeVerifiedPayload(verified));
      return res;
    } catch (e: any) {
      console.error('x402 verify failed:', e?.message || e);
      return new NextResponse(
        JSON.stringify({ error: 'Invalid or expired payment proof' }),
        { status: 402, headers: { 'Content-Type': 'application/json' } }
      );
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/api/today'],
};

API Reference

`SellerSDK`

Constructor Options

jwksUrl (required): JWKS endpoint URL
issuer (optional): Expected token issuer
audience (optional): Expected audience (project ID)
clockSkewSec (optional): Clock skew tolerance in seconds (default: 60)

Methods

`verifyProof(token, expectedResource?)`

Verify a JWT payment proof.

token: The JWT token string
expectedResource: Optional resource path to validate
Returns: VerifiedProof object with claims
Throws: Error if verification fails

`SellerSDK.extractProof(headers, cookies?)`

Static helper to extract proof token from request headers or cookies.

Verified Proof Claims

{
  resource: string;      // e.g., "/api/today"
  buyer: string;         // buyer identifier
  amount: string;        // payment amount (minor units)
  currency: string;      // e.g., "USDC"
  network: string;       // e.g., "base-sepolia"
  txHash?: string;       // transaction hash (if settled)
  proofId: string;       // unique proof identifier
  exp: number;           // expiration timestamp
  iss: string;           // issuer
  aud: string;           // audience
}

Security Notes

Tokens are short-lived (default TTL in gateway)
JWKS endpoint supports key rotation via kid (key ID)
Clock skew tolerance prevents time sync issues
Resource validation prevents token reuse across endpoints

License

MIT