npm package: @megalithlabs/x402
Description: JavaScript SDK for x402 payments - pay and charge for APIs with stablecoins
Author: Megalith Labs
Latest version: 0.1.3

# @megalithlabs/x402

JavaScript SDK for x402 payments. Pay for APIs and charge for APIs with stablecoins.

**x402** is an open protocol for internet-native payments using HTTP 402 status codes.

Learn more: [x402.org](https://x402.org) | [Megalith Labs](https://megalithlabs.ai)

---

## Installation

```bash
npm install @megalithlabs/x402
```

**For viem WalletClient support** (hardware wallets, WalletConnect, etc.):

```bash
npm install @megalithlabs/x402 viem
```

> **Note:** viem is an optional peer dependency. Only install it if you need WalletClient support for hardware wallets, WalletConnect, or other advanced wallet integrations. The simple approach using private keys works with just ethers (included by default).

---

## Quick Start

### Paying for APIs (Payer)

**Simple approach (private key):**

```javascript
const { createSigner, x402Fetch } = require('@megalithlabs/x402');

// Create signer with your wallet
const signer = await createSigner('bsc', process.env.PRIVATE_KEY);

// Wrap fetch to auto-handle 402 responses
const fetchWithPay = x402Fetch(fetch, signer, { maxAmount: '0.50' });

// Use it like normal fetch - payments happen automatically
const response = await fetchWithPay('https://api.example.com/premium-data');
const data = await response.json();
```

**Advanced approach (viem wallet client):**

> **Requires viem:** Run `npm install viem` first.

```javascript
const { createSigner, x402Fetch } = require('@megalithlabs/x402');
const { createWalletClient, http } = require('viem');
const { bsc } = require('viem/chains');
const { privateKeyToAccount } = require('viem/accounts');

// Create viem wallet client (supports hardware wallets, WalletConnect, etc.)
const walletClient = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY),
  chain: bsc,
  transport: http()
});

// Pass the wallet client directly
const signer = await createSigner(walletClient);

// Same usage from here
const fetchWithPay = x402Fetch(fetch, signer, { maxAmount: '0.50' });
const response = await fetchWithPay('https://api.example.com/premium-data');
```

### Charging for APIs (Payee)

```javascript
const express = require('express');
const { x402Express } = require('@megalithlabs/x402');

const app = express();

// USDC on bsc
const USDT = '0x55d398326f99059fF775485246999027B3197955';

// Add payment requirement to routes
app.use(x402Express('0xYourWalletAddress', {
  '/api/premium': {
    amount: '0.01',      // 0.01 USDT (human-readable)
    asset: USDT,         // Token address
    network: 'bsc'      // Network
  }
}));

app.get('/api/premium', (req, res) => {
  res.json({ data: 'premium content' });
});

app.listen(3000);
```

---

## API Reference

### createSigner(network, privateKey) OR createSigner(walletClient)

Create a signer for x402 payments. Supports two approaches:

**Simple approach (private key):**

```javascript
const signer = await createSigner('bsc', '0xabc123...');
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `network` | string |`'bsc'`, `'bsc-testnet'`, `'base'`, `'base-sepolia'`  |
| `privateKey` | string | Wallet private key (hex string) |

**Advanced approach (viem wallet client):**

> **Requires viem:** Run `npm install viem` first.

```javascript
const { createWalletClient, http } = require('viem');
const { bsc } = require('viem/chains');
const { privateKeyToAccount } = require('viem/accounts');

// With private key
const walletClient = createWalletClient({
  account: privateKeyToAccount('0xabc123...'),
  chain: bsc,
  transport: http()
});

// With hardware wallet (Ledger)
const walletClient = createWalletClient({
  account: await ledger.getAccount(),
  chain: bsc,
  transport: http()
});

// With WalletConnect
const walletClient = createWalletClient({
  account: walletConnectAccount,
  chain: bsc,
  transport: http()
});

const signer = await createSigner(walletClient);
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `walletClient` | WalletClient | viem WalletClient with account and chain configured |

The viem approach supports:
- Hardware wallets (Ledger, Trezor)
- WalletConnect
- Smart contract wallets
- MPC wallets
- Browser extension wallets

---

### x402Fetch(fetch, signer, options)

Wrap fetch to automatically handle 402 Payment Required responses.

```javascript
const fetchWithPay = x402Fetch(fetch, signer, { maxAmount: '0.50' });
const response = await fetchWithPay('https://api.example.com/data');
```

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `maxAmount` | string | **Yes** | Maximum payment per request (e.g., `'0.50'`) |
| `facilitator` | string | No | Custom facilitator URL (default: Megalith) |

---

### x402Axios(axiosInstance, signer, options)

Wrap axios to automatically handle 402 Payment Required responses.

```javascript
const axios = require('axios');
const axiosWithPay = x402Axios(axios.create(), signer, { maxAmount: '0.50' });
const response = await axiosWithPay.get('https://api.example.com/data');
```

Same options as `x402Fetch`.

---

### x402Express(payTo, routes, options)

Express middleware to require payment for routes.

```javascript
const USDC = '0x55d398326f99059fF775485246999027B3197955';

app.use(x402Express('0xYourAddress', {
  '/api/premium': { amount: '0.01', asset: USDT, network: 'bsc' },
  '/api/expensive': { amount: '1.00', asset: USDT, network: 'bsc' }
}));
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `payTo` | string | Address to receive payments |
| `routes` | object | Route → config mapping |
| `options.facilitator` | string | Custom facilitator URL |

**Route config:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | string | Yes | Amount in tokens (e.g., `'0.01'`) - human-readable |
| `asset` | string | Yes | Token contract address |
| `network` | string | Yes | Blockchain network |
| `description` | string | No | Human-readable description |

The SDK automatically fetches the token's decimals from the blockchain to convert your human-readable amount to atomic units.

---

### x402Hono(payTo, routes, options)

Hono middleware to require payment for routes.

```javascript
const { Hono } = require('hono');
const { x402Hono } = require('@megalithlabs/x402');

const USDT = '0x55d398326f99059fF775485246999027B3197955';
const app = new Hono();

app.use('*', x402Hono('0xYourAddress', {
  '/api/premium': { amount: '0.01', asset: USDT, network: 'bsc' }
}));
```

Same parameters as `x402Express`.

---

### x402Next(handler, config, options)

Wrap Next.js API route handlers with payment requirement.

```javascript
// pages/api/premium.js
const { x402Next } = require('@megalithlabs/x402');

const USDT = '0x55d398326f99059fF775485246999027B3197955';

export default x402Next(
  async (req, res) => {
    res.json({ data: 'premium content' });
  },
  {
    payTo: '0xYourAddress',
    amount: '0.01',
    asset: USDT,
    network: 'bsc'
  }
);
```

---

## Supported Networks

| Network | Chain ID | Description |
|---------|----------|-------------|
| `bsc` | 56 | BNB Chain Mainnet |
| `bsc-testnet` | 97 | BNB Chain Testnet |
| `base` | 8453 | Base Mainnet |
| `base-sepolia` | 84532 | Base Testnet |


---

## How It Works

### Payer Flow

1. Your code calls `fetchWithPay('https://api.example.com/data')`
2. API returns `402 Payment Required` with payment requirements
3. SDK reads requirements, signs payment with your wallet
4. SDK retries request with `X-PAYMENT` header
5. API verifies payment, returns data

### Payee Flow

1. Request arrives at your Express/Hono/Next server
2. Middleware checks if route requires payment
3. No `X-PAYMENT` header? Return 402 with requirements
4. Has payment? Verify and settle via facilitator
5. Payment confirmed? Continue to your route handler

---

## CLI Tools

For manual testing and learning, standalone CLI tools are available in the [x402 repository](https://github.com/MegalithLabs/x402):

```bash
git clone https://github.com/MegalithLabs/x402.git
cd x402/tools

# Create payment authorization (interactive)
node signer.js

# Approve Stargate for ERC-20 tokens
node approve.js
```

See `/tools/README.md` in the repository for details.

---

## Debugging

The SDK includes debug logging powered by the `debug` package. Enable it by setting the `DEBUG` environment variable:

```bash
# Enable all x402 debug output
DEBUG=x402:* node app.js

# Enable only payer debug (client-side)
DEBUG=x402:payer node app.js

# Enable only payee debug (server-side)
DEBUG=x402:payee node app.js

# Enable multiple namespaces
DEBUG=x402:payer,x402:signer node app.js

# Save debug output to a file
DEBUG=x402:* node app.js 2> debug.log
```

**Example output:**
```
x402:payer Request to https://api.example.com/premium +0ms
x402:payer Got 402 Payment Required +125ms
x402:payer Payment requirements: { scheme: 'exact', network: 'bsc', ... } +2ms
x402:payer Creating payment... +0ms
x402:payer Payment created, signature: 0x1a2b3c... +340ms
x402:payer Verifying payment with facilitator: https://x402.megalithlabs.ai +0ms
x402:payer Payment verified successfully +89ms
x402:payer Retrying request with X-PAYMENT header +0ms
x402:payer Final response: 200 +201ms
```

**Available namespaces:**
- `x402:payer` - Client-side payment flow (fetch/axios wrappers)
- `x402:payee` - Server-side middleware (Express/Hono/Next.js)
- `x402:signer` - Wallet signer initialization

---

## Support

- Website: https://megalithlabs.ai
- x402 Protocol: https://x402.org
- Issues: https://github.com/MegalithLabs/x402/issues
- Email: support@megalithlabs.ai

---

## License

MIT License