X402 SDK - Solana Payment Gateway

TypeScript SDK for HTTP 402 micropayments on Solana. Add pay-per-use to your APIs with one line of code.

Features: SOL/USDC payments • Express middleware • Auto verification • TypeScript

📦 Installation

npm install x402-sdk-solana

🚀 Quick Start

Client Integration

import { X402SDK } from 'x402-sdk-solana';
import { Keypair } from '@solana/web3.js';

// Initialize SDK
const sdk = new X402SDK({ network: 'solana-devnet' });

// Create payment
const payment = sdk.payments.sol(0.001, 'recipient-address');

// Execute payment
const wallet = Keypair.generate();
const result = await sdk.pay(payment, { payerKeypair: wallet });
console.log(`✅ Payment confirmed: ${result.explorerUrl}`);

Server Integration

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

const app = express();

// Add payment protection to endpoints
app.get('/premium-content', 
  createPaymentMiddleware({
    tokenType: 'SOL',
    price: 0.001,
    recipient: 'your-wallet-address',
    network: 'solana-devnet'
  }),
  (req, res) => {
    res.json({ content: 'Premium content unlocked!' });
  }
);

app.listen(3000);

� How it Works

1. Client → Server: Request protected resource
2. Server → Client: 402 Payment Required + payment details
3. Client: Creates & signs payment transaction
4. Client → Server: Retry request with X-Payment header
5. Server: Verifies payment & submits to blockchain
6. Server → Client: Protected content + payment confirmation

🛠️ API Reference

X402SDK Class

// Initialize
const sdk = new X402SDK({
  network: 'solana-devnet' | 'solana-mainnet'
});

// Payment methods
sdk.payments.sol(amount, recipient)
sdk.payments.usdc(amount, recipient)
sdk.payments.spl(amount, recipient, mintAddress, decimals)

// Execute payments
await sdk.pay(paymentConfig, { payerKeypair: wallet })
await sdk.createSignedTransaction(paymentConfig, keypair)

// Utilities
sdk.utils.getUSDCMint()
sdk.utils.getExplorerUrl(signature)

Server Middleware

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

createPaymentMiddleware({
  tokenType: 'SOL' | 'USDC',
  price: number,
  recipient: string,
  network: 'solana-devnet' | 'solana-mainnet'
})

Examples

Complete x402 Flow

// Client - handles 402 responses automatically
async function makeRequest(url: string) {
  const response = await fetch(url);
  
  if (response.status === 402) {
    // Payment required - create and send payment
    const payment = sdk.payments.sol(0.001, 'recipient-address');
    const signedTx = await sdk.createSignedTransaction(payment, wallet);
    
    // Retry with payment header
    return fetch(url, {
      headers: { 'X-Payment': signedTx.x402Header }
    });
  }
  
  return response;
}

Multiple Payment Options

// Server with different pricing tiers
const basicPayment = createPaymentMiddleware({
  tokenType: 'SOL',
  price: 0.001,
  recipient: 'your-address',
  network: 'solana-devnet'
});

const premiumPayment = createPaymentMiddleware({
  tokenType: 'USDC', 
  price: 0.01,
  recipient: 'your-address',
  network: 'solana-devnet'
});

app.get('/api/basic', basicPayment, (req, res) => {
  res.json({ data: 'Basic content' });
});

app.get('/api/premium', premiumPayment, (req, res) => {
  res.json({ data: 'Premium content' });
});

🔧 Configuration

// Development
const sdk = new X402SDK({ network: 'solana-devnet' });

// Production  
const sdk = new X402SDK({ network: 'solana-mainnet' });

🚨 Error Handling

try {
  const result = await sdk.pay(payment, { payerKeypair: wallet });
} catch (error) {
  console.log('Payment failed:', error.message);
  // Handle insufficient funds, network errors, etc.
}

📄 License

MIT License - see LICENSE file.

Built for the Solana ecosystem • npm • GitHub