x402-client

@x402/client

Easy payment requests for x402 protocol on Solana. This package provides client-side utilities for making payment-gated requests to x402-enabled servers.

Installation

npm install @x402/client

Quick Start

import { X402Client, X402Wallet } from '@x402/client';

// Create or import wallet
const wallet = X402Wallet.fromPrivateKey(privateKey);
// or generate new wallet
const wallet = X402Wallet.create();

// Create client
const client = new X402Client({
  wallet,
  facilitatorUrl: 'http://localhost:3001'
});

// Pay and fetch resource
const response = await client.payAndFetch('http://localhost:3000/premium', {
  amount: 0.01 // 0.01 SOL
});

console.log(response.data); // Premium content

Features

• 🔐 Wallet Management - Create, import, and manage Solana wallets
• 💳 Payment Creation - Generate payment requests with nonce protection
• ✍️ Transaction Signing - Sign Solana transactions and authorization payloads
• 🌐 HTTP Integration - Make payment-gated HTTP requests seamlessly
• 🛡️ Type Safety - Full TypeScript support with comprehensive types

API Reference

X402Wallet

Wallet management for x402 payments.

// Create new wallet
const wallet = X402Wallet.create();

// Import from private key
const wallet = X402Wallet.fromPrivateKey('base58-private-key');

// Import from mnemonic
const wallet = await X402Wallet.fromMnemonic('your twelve word mnemonic phrase');

// Get public key
const publicKey = wallet.getPublicKey();

// Sign message
const signature = await wallet.signMessage(messageBytes);

// Export wallet
const json = wallet.toJSON();

X402Client

Client for making payment-gated requests.

const client = new X402Client({
  wallet: myWallet,
  facilitatorUrl: 'http://localhost:3001',
  rpcUrl: 'https://api.devnet.solana.com', // optional
  defaultExpiry: 300 // optional, 5 minutes default
});

// Make payment request
const response = await client.payAndFetch(url, {
  amount: 0.01, // SOL amount
  expiry: 600, // optional, seconds
  resourceId: 'custom-id' // optional
});

// Manual payment creation
const paymentRequest = await client.createPaymentRequest(url, options, merchantAddress);

// Verify payment
const isValid = await client.verifyPayment(paymentRequest);

// Get wallet balance
const balance = await client.getBalance();

// Request airdrop (devnet only)
const signature = await client.requestAirdrop(1); // 1 SOL

Examples

Basic Payment

import { X402Client, X402Wallet } from '@x402/client';

const wallet = X402Wallet.fromPrivateKey(process.env.PRIVATE_KEY!);
const client = new X402Client({
  wallet,
  facilitatorUrl: process.env.FACILITATOR_URL!
});

try {
  const response = await client.payAndFetch('https://api.example.com/premium-data', {
    amount: 0.01
  });
  
  console.log('Premium data:', response.data);
  console.log('Transaction:', response.transactionSignature);
} catch (error) {
  console.error('Payment failed:', error);
}

Custom Payment Options

const response = await client.payAndFetch('https://api.example.com/resource', {
  amount: 0.005,
  expiry: 600, // 10 minutes
  resourceId: 'custom-resource-id'
});

Manual Payment Flow

// Create payment request
const paymentRequest = await client.createPaymentRequest(
  'https://api.example.com/resource',
  { amount: 0.01 },
  'merchant-solana-address'
);

// Verify with facilitator
const isValid = await client.verifyPayment(paymentRequest);

if (isValid) {
  // Make HTTP request with payment
  const response = await client.makePaymentRequest(
    'https://api.example.com/resource',
    { amount: 0.01 }
  );
}

Error Handling

try {
  const response = await client.payAndFetch(url, options);
} catch (error) {
  if (error.message.includes('insufficient SOL')) {
    console.log('Need more SOL in wallet');
  } else if (error.message.includes('402')) {
    console.log('Payment required but failed');
  } else {
    console.log('Other error:', error.message);
  }
}

Types

interface PaymentOptions {
  amount: number; // SOL amount
  expiry?: number; // seconds
  resourceId?: string; // custom identifier
}

interface PaymentResponse<T> {
  data: T; // response data
  verified: boolean; // payment verification status
  transactionSignature?: string; // Solana transaction hash
}

interface X402ClientConfig {
  wallet: X402Wallet;
  facilitatorUrl: string;
  rpcUrl?: string; // default: devnet
  defaultExpiry?: number; // default: 300 seconds
}

Browser Support

This package works in both Node.js and browser environments. For browsers, ensure you have proper polyfills for Node.js modules if needed.

License

MIT