x402sdk

A unified SDK around the @x402 ecosystem.

Introduction

x402unified provides a simplified, cohesive interface for interacting with various @x402 packages (@x402/core, @x402/evm, @x402/hono, @x402/paywall). It enables seamless integration of X402 payment flows, resource servers, and Web3 interactions, supporting both CommonJS (CJS) and ECMAScript Modules (ESM).

Features

• Unified API: Streamlined configuration for HTTPFacilitatorClient, x402ResourceServer, createPaywall, and ExactEvmScheme.
• Universal compatibility: Works out-of-the-box with Node.js, Express, or Hono.
• TypeScript First: Full static typing and excellent developer experience.
• Easy Middleware Integration: Dedicated hooks for modern web frameworks.

Installation

npm install x402unified
# or
yarn add x402unified
# or
pnpm add x402unified

Available Facilitators

• facilitators.OPENX402 - Register your payTo address at OpenX402 ($5 USDC)
• facilitators.LOCAL - Use your own facilitator

Quick Start

For Hono

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { HonoPaymentMiddleware, facilitators } from 'x402unified';

const app = new Hono();
const port = 3000;

const paymentProtection = HonoPaymentMiddleware({
  network: 'eip155:84532', // Base Sepolia Testnet
  facilitator: facilitators.OPENX402,
  testnet: true,
  payTo: '0x1A1a1a1A1a1A1a1A1a1A1a1A1a1a1a1A1a1A1a1A', // Change to your wallet address
  paywall: true,
  endpoints: {
    '/api/exclusive': {
      price: '$0.15',
      description: 'Exclusive Private API Endpoint'
    }
  }
});

app.get('/', (c) => c.text('Welcome to the x402 SDK Hono Example!'));

app.use('/api/*', paymentProtection);

app.get('/api/exclusive', (c) => c.json({
  success: true,
  message: 'Payment verified! You are accessing the exclusive zone.'
}));

serve({ fetch: app.fetch, port });
console.log(`Server running on port ${port}`);

For Express

import express from 'express';
import { ExpressPaymentMiddleware, facilitators } from 'x402unified';

const app = express();
const port = 3000;

const paymentProtection = ExpressPaymentMiddleware({
  network: 'eip155:84532', // Base Sepolia Testnet
  facilitator: facilitators.OPENX402,
  testnet: true,
  payTo: '0x1A1a1a1A1a1A1a1A1a1A1a1A1a1a1a1A1a1A1a1A', // Change to your wallet address
  paywall: true,
  endpoints: {
    '/api/premium': {
      price: '$0.05',
      description: 'Premium AI Generation API'
    }
  }
});

app.use(express.json());

app.get('/', (req, res) => res.send('Welcome to the x402 SDK Express Example!'));

app.use(paymentProtection);

app.get('/api/premium', (req, res) => {
  res.json({
    success: true,
    message: 'Payment verified! Here is your premium data.'
  });
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Scripts

This project includes scripts to build, test, and run examples:

• npm run build - Compile the SDK using tsup.
• npm run dev - Watch mode for compiling the SDK.
• npm run test - Run unit tests using Vitest.
• npm run example:express - Run the Express example.
• npm run example:hono - Run the Hono example.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to help out.

Support

For support, please open an issue on GitHub.

License

This project is licensed under the MIT License.