npm package: @rapid402/sdk
Description: Official TypeScript SDK for Rapid402 x402 payment facilitator on BNB Chain
Author: Rapid402
Latest version: 1.0.0

# @rapid402/sdk

Official TypeScript SDK for [Rapid402](https://rapid402.com) - 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

```bash
npm install @rapid402/sdk
```

or with yarn:

```bash
yarn add @rapid402/sdk
```

## Quick Start

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
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>`

```typescript
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>`

```typescript
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>`

```typescript
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>`

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

## Error Handling

```typescript
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
```typescript
{
  network: 'bsc-mainnet',
  chainId: 56,
  rpcUrl: 'https://bsc-dataseed.binance.org/',
  explorerUrl: 'https://bscscan.com'
}
```

### BNB Chain Testnet
```typescript
{
  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](https://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](https://rapid402.com) for complete documentation.

## License

MIT

## Support

- Documentation: [https://rapid402.com](https://rapid402.com)
- GitHub Issues: [https://github.com/rapid402/sdk/issues](https://github.com/rapid402/sdk/issues)
- Email: support@rapid402.com