x402 Quick Start Guide

Get started quickly with bex.co's x402 facilitator service as a merchant (server) or a buyer (client).

Overview​

This guide will help you:

• Merchants (Servers): Protect your APIs and content with x402 payment requirements
• Buyers (Clients): Enable your applications and AI agents to automatically pay for protected resources

Prerequisites​

Before you begin, you'll need:

1. bex.co API Key: Sign up at bex.co/dash
2. Wallet Setup: A wallet with USDC on supported networks (Sui recommended)
3. Node.js 18+ or Python 3.8+ (depending on your stack)

For Servers (Merchants)​

Installation​

npm install @bex/x402-sdk
# or
yarn add @bex/x402-sdk

Basic Server Setup​

import express from 'express';
import { X402Middleware } from '@bex/x402-sdk';
 
const app = express();
 
// Configure x402 middleware
const x402 = X402Middleware({
  apiKey: process.env.BEX_API_KEY,
  facilitatorUrl: 'https://x402.bex.co',
  network: 'sui', // Default network
  token: 'USDC',
});
 
// Protect your endpoints with x402
app.get('/api/premium/data',
  x402.require({
    amount: '0.01', // 1 cent in USDC
    network: 'sui',
  }),
  (req, res) => {
    // Payment verified - deliver content
    res.json({
      data: 'Your premium content here',
      payment: {
        txHash: req.x402.txHash,
        amount: req.x402.amount,
        network: req.x402.network,
      }
    });
  }
);
 
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

How Server Middleware Works​

1. Request arrives without payment → Middleware returns 402 Payment Required with payment details
2. Request arrives with payment → Middleware verifies signature with bex.co facilitator
3. Payment verified → Request proceeds to your handler with payment details attached
4. Verification fails → Returns 402 Payment Required with error details

For Clients (Buyers)​

Installation​

npm install @bex/x402-client
# or
yarn add @bex/x402-client

Basic Client Setup​

import { X402Client } from '@bex/x402-client';
 
// Initialize client with wallet
const client = new X402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'sui',
  facilitatorUrl: 'https://x402.bex.co',
});
 
// Fetch protected resource - payment handled automatically
async function fetchPremiumData() {
  try {
    const response = await client.fetch(
      'https://api.example.com/api/premium/data'
    );
 
    const data = await response.json();
    console.log('Data:', data);
    console.log('Payment TX:', response.headers.get('X-Payment-Response'));
  } catch (error) {
    console.error('Request failed:', error);
  }
}
 
fetchPremiumData();

How Client Library Works​

1. Makes initial request to protected endpoint
2. Receives 402 response with payment requirements
3. Signs payment authorization using your wallet
4. Retries request with X-Payment header containing signature
5. Receives content after payment verification

AI Agent Integration​

Claude MCP (Model Context Protocol)​

import { X402MCPServer } from '@bex/x402-mcp';
 
const server = new X402MCPServer({
  wallet: process.env.AGENT_WALLET_PRIVATE_KEY,
  network: 'sui',
  facilitatorUrl: 'https://x402.bex.co',
  spendingLimit: {
    daily: '10.00', // Max $10 per day
    perTransaction: '1.00', // Max $1 per transaction
  }
});
 
// Register with Claude
server.start();

Now Claude can autonomously discover and pay for x402-protected services.

LangChain Integration​

from langchain.tools import Tool
from bex_x402_client import X402Client
 
# Create x402-enabled HTTP client for agent
client = X402Client(
    private_key=os.environ["AGENT_WALLET_PRIVATE_KEY"],
    network="sui",
    facilitator_url="https://x402.bex.co",
)
 
# Create tool for LangChain agent
x402_fetch_tool = Tool(
    name="x402_fetch",
    description="Fetch data from x402-protected APIs with automatic payment",
    func=lambda url: client.get(url).json()
)
 
# Add to your agent's tools
agent_tools.append(x402_fetch_tool)

Facilitator Configuration​

bex.co Facilitator​

Facilitator URL: https://x402.bex.co

Available Endpoints:

• /verify - Verify payment signature
• /settle - Execute on-chain settlement
• /list - List supported networks and tokens

Environment Variables​

# Server configuration
BEX_API_KEY=your_api_key_here
BEX_X402_FACILITATOR=https://x402.bex.co
 
# Client configuration
WALLET_PRIVATE_KEY=your_private_key_here
X402_NETWORK=sui

Supported Networks​

bex.co's x402 facilitator supports the following networks:

Payment Configuration Options​

Server-Side Options​

X402Middleware({
  apiKey: 'your_api_key',
  facilitatorUrl: 'https://x402.bex.co',
 
  // Payment requirements
  network: 'sui',
  token: 'USDC',
  amount: '0.01',
 
  // Optional configurations
  validDuration: 300, // Payment valid for 5 minutes
  recipient: '0x742d...', // Your wallet address
 
  // Callbacks
  onPaymentReceived: (payment) => {
    console.log('Payment received:', payment);
  },
  onPaymentFailed: (error) => {
    console.error('Payment failed:', error);
  },
})

Client-Side Options​

new X402Client({
  privateKey: 'your_private_key',
  network: 'sui',
  facilitatorUrl: 'https://x402.bex.co',
 
  // Optional configurations
  maxAmount: '1.00', // Max amount to auto-pay
  requireConfirmation: true, // Prompt before payment
  timeout: 30000, // Request timeout in ms
 
  // Callbacks
  onPaymentRequired: (details) => {
    console.log('Payment required:', details);
    return true; // Return false to cancel
  },
  onPaymentComplete: (txHash) => {
    console.log('Payment complete:', txHash);
  },
})

Testing Your Integration​

Test with curl​

# 1. Request protected resource (should get 402)
curl -X GET https://api.example.com/api/premium/data \
  -H "Content-Type: application/json" \
  -v
 
# Response: 402 Payment Required
# X-Payment-Required: exact amount=0.01 token=USDC network=sui recipient=0x742d...
 
# 2. Generate payment signature (using SDK or manually)
# 3. Retry with payment header
curl -X GET https://api.example.com/api/premium/data \
  -H "Content-Type: application/json" \
  -H "X-Payment: <your_signed_payment>" \
  -v
 
# Response: 200 OK with content and X-Payment-Response header

Test with SDK​

import { X402Client } from '@bex/x402-client';
 
const client = new X402Client({
  privateKey: process.env.TEST_WALLET_KEY,
  network: 'sui-testnet', // Use testnet
  facilitatorUrl: 'https://x402.bex.co',
});
 
// Test payment flow
const response = await client.fetch(
  'http://localhost:3000/api/premium/data'
);
 
console.log('Status:', response.status);
console.log('Payment TX:', response.headers.get('X-Payment-Response'));
console.log('Data:', await response.json());

Security Best Practices​

1. Never commit private keys - Use environment variables or secure key management
2. Validate payment amounts - Check that received payments match expected amounts
3. Set spending limits - Configure max amounts for AI agents
4. Use testnet first - Test thoroughly on testnet before mainnet
5. Monitor transactions - Track payments and detect anomalies
6. Implement rate limiting - Prevent abuse of your protected endpoints
7. Log all payments - Maintain audit trail of transactions

Troubleshooting​

Common Issues​

402 Error: "Invalid signature"

• Check that your private key is correct
• Verify the network matches (mainnet vs testnet)
• Ensure client and server use same facilitator URL

402 Error: "Insufficient balance"

• Verify wallet has enough USDC
• Check wallet has enough native tokens for gas (if required)
• Confirm you're on the correct network

Timeout errors

• Increase client timeout setting
• Check network connectivity
• Verify facilitator service is operational

Payment not settling

• Check transaction on block explorer
• Verify recipient address is correct
• Ensure network is not congested

Next Steps​

• Read Introduction - Learn more about x402 protocol
• View Landing Page - bex.co x402 facilitator service
• Join Discord - Get help from community
• Join Waitlist - Get early access to bex.co x402 facilitator

Need Help?​

• Documentation: Browse our comprehensive guides
• Discord: Join our community at discord.gg/GqzTYQ4YNa
• Email: Contact hello@bex.co
• GitHub: Report issues and contribute

Ready to get started? Join the waitlist for early access to bex.co's x402 facilitator service.