x402 Solana SDK

The ultimate SDK for payment-gated APIs using USDC on Solana - Single package for all frameworks.

Transform any API into a paid service in just 2 minutes with one simple npm install. Compatible with x402 protocol.

🚀 Quick Start

Installation

npm install x402-solana-sdk

That's it! No multiple packages, no complex setup. One package for everything.

Basic Usage

import { x402, createClient, createWallet } from 'x402-solana-sdk';

// Server-side (Express.js)
app.use('/premium', x402({
  amount: 0.01, // 0.01 USDC
  payToAddress: 'YOUR_WALLET_ADDRESS'
}));

// Client-side
const wallet = createWallet();
const client = createClient({ wallet });

const response = await client.payAndFetch('/premium', {
  amount: 0.01
});

⚡ Framework Support

Express.js

import express from 'express';
import { createX402Middleware } from 'x402-solana-sdk';

const app = express();
const x402 = createX402Middleware({
  amount: 0.01,
  merchantAddress: process.env.MERCHANT_ADDRESS
});

// Require payment
app.get('/premium', x402.requirePayment(0.01), (req, res) => {
  res.json({
    message: 'Premium content unlocked!',
    payment: req.x402 // Payment details
  });
});

// Optional payment
app.get('/freemium', x402.optionalPayment(0.005), (req, res) => {
  if (req.x402.verified) {
    res.json({ content: 'Premium content' });
  } else {
    res.json({ content: 'Free content' });
  }
});

Next.js (Coming Soon)

import { withX402 } from 'x402-solana-sdk/nextjs';

export default withX402(
  async (req, res) => {
    res.json({ message: 'Paid API response' });
  },
  {
    amount: 0.01,
    merchantAddress: process.env.MERCHANT_ADDRESS
  }
);

Fastify (Coming Soon)

import { x402Plugin } from 'x402-solana-sdk/fastify';

await fastify.register(x402Plugin, {
  amount: 0.01,
  merchantAddress: process.env.MERCHANT_ADDRESS
});

fastify.get('/premium', {
  x402: { amount: 0.01 }
}, async (request, reply) => {
  return { message: 'Premium content' };
});

Hono (Coming Soon)

import { Hono } from 'hono';
import { x402 } from 'x402-solana-sdk/hono';

const app = new Hono();

app.use('/premium/*', x402({
  amount: 0.01,
  merchantAddress: process.env.MERCHANT_ADDRESS
}));

app.get('/premium/data', (c) => {
  return c.json({ data: 'Premium data' });
});

🎯 Why x402 Solana SDK?

| Traditional Setup | x402 Solana SDK | |-------------------|-----------------| | Multiple packages | Single package | | Complex configuration | 2-line setup | | Framework-specific code | Universal API | | 30+ minutes setup | 2 minutes | | 200+ lines of code | 10-20 lines |

📦 What's Included

• 🔒 Payment Verification - Ed25519 signatures, nonce protection, replay attack prevention
• 🌐 Multi-Framework - Express.js, Next.js, Fastify, Hono support
• 💎 TypeScript First - Full type safety and IntelliSense support
• 🚀 Client Library - Browser and Node.js payment client
• ⚡ Auto-Detection - Automatically detects your framework
• 🛡️ Security - Built-in security best practices
• 📱 Lightweight - Tree-shakeable, minimal bundle size

🔧 Configuration

Environment Variables

# Required
MERCHANT_ADDRESS=your_solana_wallet_address

# Optional
X402_FACILITATOR_URL=https://x402.org/facilitator
X402_NETWORK=mainnet-beta
X402_TIMEOUT=30000

Advanced Configuration

import { x402 } from 'x402-solana-sdk';

const middleware = x402({
  amount: 0.01,
  merchantAddress: process.env.MERCHANT_ADDRESS,
  facilitatorUrl: 'https://custom-facilitator.com',
  network: 'devnet',
  timeout: 60000,
  skipPaths: ['/health', '/metrics'],
  errorHandler: (error, req, res, next) => {
    console.error('Payment error:', error);
    res.status(500).json({ error: 'Payment processing failed' });
  }
});

🧪 Testing

import { createWallet, createClient } from 'x402-solana-sdk';

// Create test wallet
const wallet = createWallet();
console.log('Test wallet:', wallet.publicKey);

// Create test client
const client = createClient({
  wallet,
  facilitatorUrl: 'http://localhost:3001', // Your test facilitator
  network: 'devnet'
});

// Test payment
try {
  const response = await client.payAndFetch('http://localhost:3000/premium', {
    amount: 0.01
  });
  console.log('Success:', response);
} catch (error) {
  console.error('Payment failed:', error.message);
}

📚 API Reference

Core Functions

• x402(options) - Universal middleware function
• createClient(options) - Create payment client
• createWallet() - Create new wallet
• createPaymentGate(amount, address) - Quick setup

Types

interface PaymentOptions {
  amount: number;
  merchantAddress: string;
  facilitatorUrl?: string;
  network?: 'mainnet-beta' | 'devnet' | 'testnet';
  timeout?: number;
}

interface ClientOptions {
  wallet: WalletInterface;
  facilitatorUrl?: string;
  network?: 'mainnet-beta' | 'devnet' | 'testnet';
  timeout?: number;
}

🌟 Examples

Simple Premium API

import express from 'express';
import { x402 } from 'x402-solana-sdk';

const app = express();

// Free endpoint
app.get('/free', (req, res) => {
  res.json({ message: 'Free content' });
});

// Premium endpoint - 0.01 SOL
app.get('/premium', 
  x402({ amount: 0.01, merchantAddress: process.env.MERCHANT_ADDRESS }),
  (req, res) => {
    res.json({
      message: 'Premium content unlocked!',
      paidAmount: req.x402.amount,
      signature: req.x402.signature
    });
  }
);

app.listen(3000);

Client Usage

import { createClient, createWallet } from 'x402-solana-sdk';

const wallet = createWallet();
const client = createClient({ wallet });

// Pay and access premium content
const premiumData = await client.payAndFetch('http://localhost:3000/premium', {
  amount: 0.01
});

console.log('Premium data:', premiumData);

🔗 Links

• GitHub: envexx
• Telegram Community: Join our community
• Documentation: Full Documentation

📝 License

MIT License - see LICENSE file for details.

Ready to transform your APIs? Start with npm install x402-solana-sdk 🚀