@wazabiai/x402 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Wazabi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,356 @@
+# @wazabiai/x402
+
+<div align="center">
+
+**Production-ready SDK for the x402 v2 Payment Protocol on BNB Smart Chain**
+
+[![npm version](https://img.shields.io/npm/v/@wazabiai/x402)](https://www.npmjs.com/package/@wazabiai/x402)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+
+</div>
+
+---
+
+## Overview
+
+The x402 protocol standardizes crypto payments over HTTP, enabling seamless pay-per-use APIs and premium content access on the blockchain.
+
+**Protocol Flow:**
+1. **402 Payment Required** — Server responds with payment details in headers
+2. **EIP-712 Signing** — Client signs typed data payload
+3. **Retry with Signature** — Client retries with `X-PAYMENT-SIGNATURE` header
+4. **Verification** — Server verifies signature and processes request
+
+## Installation
+
+```bash
+npm install @wazabiai/x402
+# or
+pnpm add @wazabiai/x402
+# or
+yarn add @wazabiai/x402
+```
+
+**Peer Dependencies:**
+```bash
+npm install viem express
+```
+
+## Quick Start
+
+### Client Usage
+
+```typescript
+import { X402Client } from '@wazabiai/x402/client';
+
+// Create client with private key (for server-to-server)
+const client = new X402Client({
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+// Make requests - 402 responses are handled automatically
+const response = await client.fetch('https://api.example.com/premium-data');
+console.log(response.data);
+```
+
+### Server Usage
+
+```typescript
+import express from 'express';
+import { x402Middleware } from '@wazabiai/x402/server';
+import { BSC_USDT, parseTokenAmount } from '@wazabiai/x402/chains';
+
+const app = express();
+
+// Protect routes with payment requirement
+app.use('/api/paid', x402Middleware({
+  recipientAddress: '0xYourWalletAddress',
+  amount: parseTokenAmount('0.10', BSC_USDT.address).toString(), // $0.10 USDT
+  tokenAddress: BSC_USDT.address,
+  description: 'Access to premium API',
+}));
+
+app.get('/api/paid/data', (req, res) => {
+  // Payment verified ✓
+  res.json({ premium: 'content' });
+});
+
+app.listen(3000);
+```
+
+## API Reference
+
+### Client
+
+#### `X402Client`
+
+```typescript
+import { X402Client } from '@wazabiai/x402/client';
+
+const client = new X402Client({
+  // Private key for signing (hex, with or without 0x)
+  privateKey?: string;
+  
+  // Custom RPC URL (defaults to BSC public RPC)
+  rpcUrl?: string;
+  
+  // Supported networks (defaults to ['eip155:56'])
+  supportedNetworks?: string[];
+  
+  // Payment deadline in seconds (default: 300)
+  defaultDeadline?: number;
+  
+  // Auto-retry on 402 (default: true)
+  autoRetry?: boolean;
+  
+  // Maximum retry attempts (default: 1)
+  maxRetries?: number;
+  
+  // Callbacks
+  onPaymentRequired?: (requirement: PaymentRequirement) => void;
+  onPaymentSigned?: (payment: SignedPayment) => void;
+});
+```
+
+**Methods:**
+
+```typescript
+// Generic fetch with automatic 402 handling
+await client.fetch(url, options);
+
+// HTTP verb shortcuts
+await client.get(url, options);
+await client.post(url, data, options);
+await client.put(url, data, options);
+await client.delete(url, options);
+
+// Manual signing
+const signedPayment = await client.signPayment(requirement);
+```
+
+### Server
+
+#### `x402Middleware`
+
+```typescript
+import { x402Middleware } from '@wazabiai/x402/server';
+
+const middleware = x402Middleware({
+  // Required: Payment recipient address
+  recipientAddress: '0x...',
+  
+  // Required: Amount in smallest token unit (wei)
+  amount: '1000000000000000000',
+  
+  // Token address (default: BSC-USDT)
+  tokenAddress?: '0x...',
+  
+  // External facilitator URL for verification
+  facilitatorUrl?: string;
+  
+  // Payment description
+  description?: string;
+  
+  // Network ID (default: 'eip155:56')
+  networkId?: string;
+  
+  // Deadline duration in seconds (default: 300)
+  deadlineDuration?: number;
+  
+  // Custom verification logic
+  verifyPayment?: (payment, req) => Promise<boolean>;
+  
+  // Routes to exclude from payment
+  excludeRoutes?: string[];
+});
+```
+
+#### Utility Functions
+
+```typescript
+import { 
+  createPaymentRequirement,
+  verifyPayment,
+  parsePaymentFromRequest
+} from '@wazabiai/x402/server';
+
+// Create a payment requirement manually
+const requirement = createPaymentRequirement({
+  recipientAddress: '0x...',
+  amount: '1000000000000000000',
+  resource: '/api/resource',
+});
+
+// Verify a signed payment
+const result = await verifyPayment(
+  signedPayment,
+  recipientAddress,
+  'eip155:56'
+);
+
+// Parse payment from Express request
+const payment = parsePaymentFromRequest(req);
+```
+
+### Types
+
+```typescript
+import type {
+  PaymentRequirement,
+  PaymentPayload,
+  SignedPayment,
+  NetworkConfig,
+  TokenConfig,
+} from '@wazabiai/x402/types';
+```
+
+### Chain Configuration
+
+```typescript
+import {
+  BSC_CHAIN_ID,        // 56
+  BSC_CAIP_ID,         // 'eip155:56'
+  BSC_USDT,            // TokenConfig
+  BSC_USDC,            // TokenConfig
+  BSC_TOKENS,          // All tokens
+  formatTokenAmount,   // Convert wei to readable
+  parseTokenAmount,    // Convert readable to wei
+} from '@wazabiai/x402/chains';
+```
+
+## Supported Tokens (BSC)
+
+| Token | Address | Decimals |
+|-------|---------|----------|
+| USDT  | `0x55d398326f99059fF775485246999027B3197955` | 18 |
+| USDC  | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` | 18 |
+| BUSD  | `0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56` | 18 |
+| WBNB  | `0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c` | 18 |
+
+## Protocol Details
+
+### HTTP Headers
+
+| Header | Direction | Description |
+|--------|-----------|-------------|
+| `X-PAYMENT-REQUIRED` | Response | JSON payment requirement |
+| `X-PAYMENT-SIGNATURE` | Request | EIP-712 signature |
+| `X-PAYMENT-PAYLOAD` | Request | JSON payment payload |
+
+### EIP-712 Structure
+
+**Domain:**
+```typescript
+{
+  name: 'x402',
+  version: '2.0.0',
+  chainId: 56  // BSC
+}
+```
+
+**Payment Type:**
+```typescript
+{
+  Payment: [
+    { name: 'amount', type: 'uint256' },
+    { name: 'token', type: 'address' },
+    { name: 'chainId', type: 'uint256' },
+    { name: 'payTo', type: 'address' },
+    { name: 'payer', type: 'address' },
+    { name: 'deadline', type: 'uint256' },
+    { name: 'nonce', type: 'string' },
+    { name: 'resource', type: 'string' },
+  ]
+}
+```
+
+## Error Handling
+
+```typescript
+import {
+  PaymentRequiredError,
+  PaymentVerificationError,
+  UnsupportedNetworkError,
+  PaymentExpiredError,
+} from '@wazabiai/x402/client';
+
+try {
+  await client.fetch(url);
+} catch (error) {
+  if (error instanceof PaymentRequiredError) {
+    console.log('Payment needed:', error.requirement);
+  }
+  if (error instanceof UnsupportedNetworkError) {
+    console.log('Unsupported network:', error.details);
+  }
+}
+```
+
+## Examples
+
+### Pay-per-API-Call
+
+```typescript
+// Server
+app.use('/api/ai', x402Middleware({
+  recipientAddress: TREASURY,
+  amount: parseTokenAmount('0.001', BSC_USDT.address).toString(),
+  description: 'AI API call',
+}));
+
+app.post('/api/ai/generate', async (req, res) => {
+  const { x402 } = req as X402Request;
+  console.log(`Payment from: ${x402?.signer}`);
+  
+  const result = await generateAIResponse(req.body);
+  res.json(result);
+});
+```
+
+### Tiered Pricing
+
+```typescript
+const PRICES = {
+  basic: '100000000000000000',    // 0.1 USDT
+  premium: '1000000000000000000', // 1 USDT
+};
+
+app.use('/api/basic', x402Middleware({
+  recipientAddress: TREASURY,
+  amount: PRICES.basic,
+}));
+
+app.use('/api/premium', x402Middleware({
+  recipientAddress: TREASURY,
+  amount: PRICES.premium,
+}));
+```
+
+### With Facilitator
+
+```typescript
+// Offload verification to external service
+app.use('/api/paid', x402Middleware({
+  recipientAddress: TREASURY,
+  amount: PRICE,
+  facilitatorUrl: 'https://facilitator.example.com',
+}));
+```
+
+## Environment Variables
+
+```bash
+# Client
+X402_PRIVATE_KEY=0x...  # Used by createX402ClientFromEnv()
+```
+
+## License
+
+MIT © Wazabi
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ for the decentralized web</sub>
+</div>

package/dist/bnb-BhqGnGQ1.d.cts

@@ -0,0 +1,98 @@
+import { TokenConfig, NetworkConfig } from './types/index.cjs';
+
+/**
+ * BNB Smart Chain (BSC) Mainnet Chain ID
+ */
+declare const BSC_CHAIN_ID: 56;
+/**
+ * BNB Smart Chain CAIP-2 Identifier
+ */
+declare const BSC_CAIP_ID: "eip155:56";
+/**
+ * BNB Smart Chain public RPC endpoints
+ * Using multiple for fallback support
+ */
+declare const BSC_RPC_URLS: readonly ["https://bsc-dataseed.binance.org", "https://bsc-dataseed1.binance.org", "https://bsc-dataseed2.binance.org", "https://bsc-dataseed3.binance.org", "https://bsc-dataseed4.binance.org", "https://bsc-dataseed1.defibit.io", "https://bsc-dataseed1.ninicoin.io"];
+/**
+ * Default BSC RPC URL
+ */
+declare const BSC_DEFAULT_RPC: "https://bsc-dataseed.binance.org";
+/**
+ * BscScan block explorer URL
+ */
+declare const BSC_BLOCK_EXPLORER: "https://bscscan.com";
+/**
+ * BSC-USDT (Tether USD) Token Configuration
+ * @see https://bscscan.com/token/0x55d398326f99059fF775485246999027B3197955
+ */
+declare const BSC_USDT: TokenConfig;
+/**
+ * BSC-USDC (USD Coin) Token Configuration
+ * @see https://bscscan.com/token/0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d
+ */
+declare const BSC_USDC: TokenConfig;
+/**
+ * BSC-BUSD (Binance USD) Token Configuration
+ * @see https://bscscan.com/token/0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56
+ */
+declare const BSC_BUSD: TokenConfig;
+/**
+ * Wrapped BNB (WBNB) Token Configuration
+ * @see https://bscscan.com/token/0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c
+ */
+declare const BSC_WBNB: TokenConfig;
+/**
+ * Default token for payments (BSC-USDT)
+ */
+declare const BSC_DEFAULT_TOKEN: TokenConfig;
+/**
+ * All supported tokens on BSC
+ */
+declare const BSC_TOKENS: {
+    readonly USDT: TokenConfig;
+    readonly USDC: TokenConfig;
+    readonly BUSD: TokenConfig;
+    readonly WBNB: TokenConfig;
+};
+/**
+ * Token address to config mapping for quick lookup
+ */
+declare const BSC_TOKEN_BY_ADDRESS: Record<string, TokenConfig>;
+/**
+ * Complete BNB Smart Chain network configuration
+ */
+declare const BSC_NETWORK_CONFIG: NetworkConfig;
+/**
+ * Get token configuration by address
+ */
+declare function getTokenByAddress(address: string): TokenConfig | undefined;
+/**
+ * Get token configuration by symbol
+ */
+declare function getTokenBySymbol(symbol: string): TokenConfig | undefined;
+/**
+ * Check if a token address is supported on BSC
+ */
+declare function isTokenSupported(address: string): boolean;
+/**
+ * Format token amount from wei to human-readable string
+ */
+declare function formatTokenAmount(amount: bigint | string, tokenAddress: string): string;
+/**
+ * Parse human-readable amount to wei
+ */
+declare function parseTokenAmount(amount: string, tokenAddress: string): bigint;
+/**
+ * Get BscScan URL for a transaction
+ */
+declare function getTxUrl(txHash: string): string;
+/**
+ * Get BscScan URL for an address
+ */
+declare function getAddressUrl(address: string): string;
+/**
+ * Get BscScan URL for a token
+ */
+declare function getTokenUrl(tokenAddress: string): string;
+
+export { BSC_CHAIN_ID as B, BSC_CAIP_ID as a, BSC_RPC_URLS as b, BSC_DEFAULT_RPC as c, BSC_BLOCK_EXPLORER as d, BSC_USDT as e, BSC_USDC as f, BSC_BUSD as g, BSC_WBNB as h, BSC_DEFAULT_TOKEN as i, BSC_TOKENS as j, BSC_TOKEN_BY_ADDRESS as k, BSC_NETWORK_CONFIG as l, getTokenByAddress as m, getTokenBySymbol as n, isTokenSupported as o, formatTokenAmount as p, parseTokenAmount as q, getTxUrl as r, getAddressUrl as s, getTokenUrl as t };

package/dist/bnb-SixQcDqs.d.ts

@@ -0,0 +1,98 @@
+import { TokenConfig, NetworkConfig } from './types/index.js';
+
+/**
+ * BNB Smart Chain (BSC) Mainnet Chain ID
+ */
+declare const BSC_CHAIN_ID: 56;
+/**
+ * BNB Smart Chain CAIP-2 Identifier
+ */
+declare const BSC_CAIP_ID: "eip155:56";
+/**
+ * BNB Smart Chain public RPC endpoints
+ * Using multiple for fallback support
+ */
+declare const BSC_RPC_URLS: readonly ["https://bsc-dataseed.binance.org", "https://bsc-dataseed1.binance.org", "https://bsc-dataseed2.binance.org", "https://bsc-dataseed3.binance.org", "https://bsc-dataseed4.binance.org", "https://bsc-dataseed1.defibit.io", "https://bsc-dataseed1.ninicoin.io"];
+/**
+ * Default BSC RPC URL
+ */
+declare const BSC_DEFAULT_RPC: "https://bsc-dataseed.binance.org";
+/**
+ * BscScan block explorer URL
+ */
+declare const BSC_BLOCK_EXPLORER: "https://bscscan.com";
+/**
+ * BSC-USDT (Tether USD) Token Configuration
+ * @see https://bscscan.com/token/0x55d398326f99059fF775485246999027B3197955
+ */
+declare const BSC_USDT: TokenConfig;
+/**
+ * BSC-USDC (USD Coin) Token Configuration
+ * @see https://bscscan.com/token/0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d
+ */
+declare const BSC_USDC: TokenConfig;
+/**
+ * BSC-BUSD (Binance USD) Token Configuration
+ * @see https://bscscan.com/token/0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56
+ */
+declare const BSC_BUSD: TokenConfig;
+/**
+ * Wrapped BNB (WBNB) Token Configuration
+ * @see https://bscscan.com/token/0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c
+ */
+declare const BSC_WBNB: TokenConfig;
+/**
+ * Default token for payments (BSC-USDT)
+ */
+declare const BSC_DEFAULT_TOKEN: TokenConfig;
+/**
+ * All supported tokens on BSC
+ */
+declare const BSC_TOKENS: {
+    readonly USDT: TokenConfig;
+    readonly USDC: TokenConfig;
+    readonly BUSD: TokenConfig;
+    readonly WBNB: TokenConfig;
+};
+/**
+ * Token address to config mapping for quick lookup
+ */
+declare const BSC_TOKEN_BY_ADDRESS: Record<string, TokenConfig>;
+/**
+ * Complete BNB Smart Chain network configuration
+ */
+declare const BSC_NETWORK_CONFIG: NetworkConfig;
+/**
+ * Get token configuration by address
+ */
+declare function getTokenByAddress(address: string): TokenConfig | undefined;
+/**
+ * Get token configuration by symbol
+ */
+declare function getTokenBySymbol(symbol: string): TokenConfig | undefined;
+/**
+ * Check if a token address is supported on BSC
+ */
+declare function isTokenSupported(address: string): boolean;
+/**
+ * Format token amount from wei to human-readable string
+ */
+declare function formatTokenAmount(amount: bigint | string, tokenAddress: string): string;
+/**
+ * Parse human-readable amount to wei
+ */
+declare function parseTokenAmount(amount: string, tokenAddress: string): bigint;
+/**
+ * Get BscScan URL for a transaction
+ */
+declare function getTxUrl(txHash: string): string;
+/**
+ * Get BscScan URL for an address
+ */
+declare function getAddressUrl(address: string): string;
+/**
+ * Get BscScan URL for a token
+ */
+declare function getTokenUrl(tokenAddress: string): string;
+
+export { BSC_CHAIN_ID as B, BSC_CAIP_ID as a, BSC_RPC_URLS as b, BSC_DEFAULT_RPC as c, BSC_BLOCK_EXPLORER as d, BSC_USDT as e, BSC_USDC as f, BSC_BUSD as g, BSC_WBNB as h, BSC_DEFAULT_TOKEN as i, BSC_TOKENS as j, BSC_TOKEN_BY_ADDRESS as k, BSC_NETWORK_CONFIG as l, getTokenByAddress as m, getTokenBySymbol as n, isTokenSupported as o, formatTokenAmount as p, parseTokenAmount as q, getTxUrl as r, getAddressUrl as s, getTokenUrl as t };