Status: {status}
{data &&
{JSON.stringify(data, null, 2)}}
);
}
```
---
## For Sellers: Creating Protected Endpoints
As a seller, create endpoints that return `402 Payment Required` when no payment is provided.
### Next.js API Route
```typescript
// pages/api/protected/resource.ts
import type { NextApiRequest, NextApiResponse } from 'next';
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
// Check for payment header
const paymentHeader = req.headers['x-payment'];
if (!paymentHeader) {
// Return 402 Payment Required
// Facilitator address is optional - SDK uses default if not provided
return res.status(402).json({
scheme: 'exact',
amount: '0.001', // Amount in PUSH tokens
currency: 'PUSH',
recipient: '0xYourSellerWalletAddress', // Your wallet address
network: 'push',
chainId: 42101,
// facilitator is optional - SDK has default: 0x30C833dB38be25869B20FdA61f2ED97196Ad4aC7
});
}
// Payment provided - return protected resource
return res.status(200).json({
success: true,
data: {
message: 'This is protected content',
timestamp: new Date().toISOString(),
},
});
}
```
### Express.js
```typescript
app.get('/api/protected/resource', (req, res) => {
const paymentHeader = req.headers['x-payment'];
if (!paymentHeader) {
return res.status(402).json({
scheme: 'exact',
amount: '0.001',
currency: 'PUSH',
recipient: '0xYourSellerWalletAddress',
network: 'push',
chainId: 42101,
// facilitator is optional - SDK uses default
});
}
res.json({ success: true, data: { /* your data */ } });
});
```
### Payment Requirements Format
Your 402 response must include:
```typescript
{
scheme: 'exact', // Payment scheme
amount: '0.001', // Amount as string
currency: 'PUSH', // Currency name
recipient: '0x...', // Your wallet address (required)
network: 'push', // Network name
chainId: 42101, // Chain ID
// facilitator is optional - SDK uses default if not provided
}
```
**Required fields:** `amount`, `currency`, `recipient`, `network`, `chainId`
**Optional fields:** `facilitator` (SDK has default: `0x30C833dB38be25869B20FdA61f2ED97196Ad4aC7`)
**Alternative field names** (SDK supports both):
- `amount` or `maxAmountRequired`
- `currency` or `asset`
- `recipient` or `payTo`
---
## New Features: Simplified Configuration
The SDK now supports multiple ways to configure it, making it much easier to use:
### 1. Environment Variables (Recommended for Production)
Set environment variables and the SDK will automatically use them:
```bash
# .env file or environment variables
PUSH_X402_FACILITATOR_ADDRESS=0x30C833dB38be25869B20FdA61f2ED97196Ad4aC7
PUSH_X402_CHAIN_ID=42101
PUSH_X402_RPC_URL=https://evm.rpc-testnet-donut-node1.push.org/
PUSH_X402_PRIVATE_KEY=your_private_key_here # Server-side only!
```
```typescript
import { createX402Client } from 'push-x402';
// SDK automatically reads from environment variables
const client = createX402Client({
walletProvider: provider, // Only payment method needs to be provided
});
// Or with private key (server-side)
const client = createX402Client({
// privateKey is read from PUSH_X402_PRIVATE_KEY automatically
});
```
### 2. Network Presets
Use preset configurations for common networks:
```typescript
import { createX402Client } from 'push-x402';
// Push Chain testnet (default)
const client = createX402Client({
network: 'push-testnet',
walletProvider: provider,
});
// Push Chain mainnet
const client = createX402Client({
network: 'push-mainnet',
walletProvider: provider,
});
```
### 3. Builder Pattern (Fluent API)
Use the builder pattern for a more readable configuration:
```typescript
import { X402ClientBuilder } from 'push-x402';
// Fluent API - much more readable!
const client = X402ClientBuilder
.forTestnet()
.withWallet(provider)
.withStatusCallback((status) => console.log(status))
.withBaseURL('https://api.example.com')
.withDebug(true)
.build();
// Or for mainnet
const client = X402ClientBuilder
.forMainnet()
.withPrivateKey(process.env.PRIVATE_KEY)
.build();
```
### 4. Debug Mode
Enable detailed logging to see exactly what's happening:
```typescript
const client = createX402Client({
walletProvider: provider,
debug: true, // Enable debug logging
});
// Or with builder
const client = X402ClientBuilder
.forTestnet()
.withWallet(provider)
.withDebug(true)
.build();
```
Debug mode logs:
- Client creation details
- 402 response detection
- Payment requirements validation
- Payment processing steps
- Transaction details
- Retry attempts
- Error details with error codes
### 5. Enhanced Error Handling
The SDK now provides structured errors with error codes:
```typescript
import { X402Error, X402ErrorCode } from 'push-x402';
try {
const response = await client.get('/protected/resource');
} catch (error) {
if (error instanceof X402Error) {
switch (error.code) {
case X402ErrorCode.PAYMENT_REQUIRED:
// Handle payment required
break;
case X402ErrorCode.INSUFFICIENT_FUNDS:
// Handle insufficient funds
console.error('Please add funds to your wallet');
break;
case X402ErrorCode.PAYMENT_FAILED:
// Handle payment failure
break;
case X402ErrorCode.NETWORK_ERROR:
// Handle network issues
break;
default:
console.error('Payment error:', error.message);
}
}
}
```
**Error Codes:**
- `PAYMENT_REQUIRED` - 402 response received
- `INSUFFICIENT_FUNDS` - Wallet doesn't have enough balance
- `PAYMENT_FAILED` - Payment processing failed
- `INVALID_PAYMENT_REQUIREMENTS` - Invalid 402 response format
- `PAYMENT_METHOD_NOT_AVAILABLE` - No payment method configured
- `TRANSACTION_FAILED` - Blockchain transaction failed
- `NETWORK_ERROR` - Network connectivity issue
- `MAX_RETRIES_EXCEEDED` - Maximum retry attempts reached
- `UNKNOWN_ERROR` - Unexpected error
## Configuration
All configuration is **optional** - the SDK works out of the box with sensible defaults!
```typescript
interface X402ClientConfig {
/**
* Optional: Base URL for API calls
* If not provided, use full URLs in requests
*/
baseURL?: string;
/**
* Optional: Custom axios request config
* Merged with default axios instance config
*/
axiosConfig?: AxiosRequestConfig;
/**
* Optional: Callback for payment status updates
* Called with status messages during payment processing
*/
onPaymentStatus?: (status: string) => void;
/**
* Optional: Custom payment endpoint for server-side processing
* If not provided, SDK will use direct facilitator contract calls (walletProvider/privateKey/universalSigner)
* Only use this if you have your own payment processing server
*
* @example
* ```typescript
* // Use your own server endpoint
* const client = createX402Client({
* paymentEndpoint: 'https://your-server.com/api/payment/process'
* });
* ```
*/
paymentEndpoint?: string;
/**
* Optional: Facilitator contract address
* Default: 0x30C833dB38be25869B20FdA61f2ED97196Ad4aC7
*/
facilitatorAddress?: string;
/**
* Optional: Chain ID
* Default: 42101 (Push Chain testnet)
*/
chainId?: number | string;
/**
* Optional: Buyer's private key for seamless transactions (agents/server-side)
* ⚠️ WARNING: Only use in secure server-side environments!
* Never expose private keys in client-side code or public repositories.
* If provided, transactions will be signed automatically without manual approval.
* Perfect for automated agents and server-side applications.
*/
privateKey?: string;
/**
* Optional: Network preset ('push-testnet' or 'push-mainnet')
* When provided, automatically sets facilitatorAddress, chainId, and pushChainRpcUrl
* Can be overridden by explicit config values
*/
network?: 'push-testnet' | 'push-mainnet';
/**
* Optional: Wallet provider for browser/client-side transactions
* Accepts ethers.js providers (e.g., window.ethereum from MetaMask)
* If provided, transactions will prompt user for approval in their wallet.
* Perfect for browser applications where users have wallet extensions.
* Requires: npm install ethers
*/
walletProvider?: WalletProvider;
/**
* Optional: Universal Signer from Push Chain SDK for multi-chain support
* If provided, enables automatic cross-chain transactions across all Push Chain supported networks.
* Takes priority over walletProvider/privateKey for multi-chain support.
* Requires: npm install @pushchain/core
*/
universalSigner?: UniversalSigner;
/**
* Optional: Enable debug mode for detailed logging
* When enabled, logs all payment flow steps, timing information, and transaction details
*/
debug?: boolean;
/**
* Optional: Push Chain RPC URL for Universal Signer chain detection
* If not provided, will auto-detect from payment requirements or use default Push Chain testnet RPC
*/
pushChainRpcUrl?: string;
/**
* Optional: Mapping of chain IDs to RPC URLs for multi-chain support
* Used for automatic chain detection from payment requirements
*
* @example
* ```typescript
* {
* '42101': 'https://evm.rpc-testnet-donut-node1.push.org/',
* '1': 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
* '137': 'https://polygon-rpc.com'
* }
* ```
*/
chainRpcMap?: Record