@rapid402/sdk

Official TypeScript SDK for Rapid402 - an x402 payment facilitator on BNB Chain.

Features

• ✅ Full TypeScript support with type definitions
• ✅ Verify payment payloads with cryptographic signature validation
• ✅ Settle payments on-chain (BNB Chain)
• ✅ Check facilitator health status
• ✅ Query supported networks and assets
• ✅ Built-in error handling
• ✅ Zero dependencies (uses native fetch)

Installation

npm install @rapid402/sdk

or with yarn:

yarn add @rapid402/sdk

Quick Start

import { Rapid402Client } from '@rapid402/sdk';

// Initialize the client
const client = new Rapid402Client({
  baseUrl: 'https://rapid402.com/api/v1',
  network: 'bsc-mainnet'
});

// Check health
const health = await client.health();
console.log(health);

// Get supported networks and assets
const supported = await client.supported();
console.log(supported.networks);

Payment Verification

// Verify a payment payload
const verification = await client.verify({
  paymentPayload: {
    scheme: 'exact',
    network: 'bsc-mainnet',
    payload: {
      from: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
      to: '0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199',
      value: '1000000000000000000', // 1 USDT
      validAfter: '0',
      validBefore: '999999999999',
      nonce: '0x1234567890abcdef',
      v: '0x1b',
      r: '0x...',
      s: '0x...'
    }
  },
  paymentRequirements: {
    scheme: 'exact',
    network: 'bsc-mainnet',
    payTo: '0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199',
    maxAmountRequired: '1000000000000000000'
  }
});

if (verification.isValid) {
  console.log(`Payment verified from: ${verification.payer}`);
}

Payment Settlement

// Settle a verified payment on-chain
const settlement = await client.settle({
  paymentPayload: {
    // ... same as verification
  },
  paymentRequirements: {
    // ... same as verification
  }
});

if (settlement.isValid) {
  console.log(`Transaction hash: ${settlement.transactionHash}`);
  console.log(`Payer: ${settlement.payer}`);
}

Configuration

interface Rapid402Config {
  baseUrl: string;                           // Required: Facilitator API endpoint
  network?: 'bsc-mainnet' | 'bsc-testnet';  // Optional: Default network (default: 'bsc-mainnet')
  apiKey?: string;                           // Optional: API key for authentication
  timeout?: number;                          // Optional: Request timeout in ms (default: 30000)
}

API Reference

client.verify(request)

Verify a payment payload with cryptographic signature validation.

Parameters:

• request.paymentPayload: The signed payment payload from the client
• request.paymentRequirements: The payment requirements from your resource server

Returns: Promise<VerifyPaymentResponse>

interface VerifyPaymentResponse {
  isValid: boolean;
  payer?: string;      // Payer address if valid
  error?: string;      // Error message if invalid
}

client.settle(request)

Settle a verified payment on-chain.

Parameters:

• request.paymentPayload: The signed payment payload
• request.paymentRequirements: The payment requirements

Returns: Promise<SettlePaymentResponse>

interface SettlePaymentResponse {
  isValid: boolean;
  payer?: string;           // Payer address
  transactionHash?: string; // On-chain transaction hash
  error?: string;           // Error message if failed
}

client.health()

Check the health status of the facilitator service.

Returns: Promise<HealthResponse>

interface HealthResponse {
  status: 'healthy';
  uptime: number;    // Uptime in seconds
  version: string;   // API version
  network?: string;  // Current network
}

client.supported()

Get list of supported networks, assets, and payment schemes.

Returns: Promise<SupportedResponse>

interface SupportedResponse {
  networks: NetworkInfo[];
  paymentSchemes: string[];
  assets: AssetInfo[];
  capabilities: string[];
}

Error Handling

import { Rapid402Error } from '@rapid402/sdk';

try {
  const result = await client.verify(request);
} catch (error) {
  if (error instanceof Rapid402Error) {
    console.error('API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('HTTP Status:', error.statusCode);
    console.error('Details:', error.details);
  }
}

Networks

BNB Chain Mainnet

{
  network: 'bsc-mainnet',
  chainId: 56,
  rpcUrl: 'https://bsc-dataseed.binance.org/',
  explorerUrl: 'https://bscscan.com'
}

BNB Chain Testnet

{
  network: 'bsc-testnet',
  chainId: 97,
  rpcUrl: 'https://data-seed-prebsc-1-s1.binance.org:8545/',
  explorerUrl: 'https://testnet.bscscan.com'
}

Supported Assets

• USDT (Tether USD) on BNB Chain
• More assets coming soon

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (if using TypeScript)

About x402 Protocol

The x402 protocol is an HTTP-based payment protocol that enables developers running resource servers to accept payments from users using cryptographically signed payloads. Learn more at x402.org.

About Rapid402

Rapid402 is an x402 payment facilitator on BNB Chain that enables AI agents to autonomously search, purchase, and pay for resources. It utilizes the chain's low-cost and high-efficiency to bridge intelligent automation and real-world commerce.

Visit rapid402.com for complete documentation.

License

MIT

Support

• Documentation: https://rapid402.com
• GitHub Issues: https://github.com/rapid402/sdk/issues
• Email: [email protected]