Quick Start Guide

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

Coming Soon

BlockEden.xyz's x402 facilitator service is currently in development. This guide shows the planned API structure. Join the waitlist for early access.

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. BlockEden.xyz API Key: Sign up at blockeden.xyz/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

TypeScript

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

Python

pip install blockeden-x402

Basic Server Setup

TypeScript (Express)

import express from 'express';
import { X402Middleware } from '@blockeden/x402-sdk';

const app = express();

// Configure x402 middleware
const x402 = X402Middleware({
  apiKey: process.env.BLOCKEDEN_API_KEY,
  facilitatorUrl: 'https://x402.blockeden.xyz',
  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');
});

TypeScript (Hono)

import { Hono } from 'hono';
import { x402Middleware } from '@blockeden/x402-sdk/hono';

const app = new Hono();

// Configure x402 middleware
app.use('/api/premium/*', x402Middleware({
  apiKey: process.env.BLOCKEDEN_API_KEY,
  facilitatorUrl: 'https://x402.blockeden.xyz',
  network: 'sui',
  token: 'USDC',
  amount: '0.01',
}));

app.get('/api/premium/data', (c) => {
  const payment = c.get('x402');

  return c.json({
    data: 'Your premium content here',
    payment: {
      txHash: payment.txHash,
      amount: payment.amount,
    }
  });
});

export default app;

Python (FastAPI)

from fastapi import FastAPI, Depends
from blockeden_x402 import X402Middleware, X402Payment

app = FastAPI()

# Configure x402 middleware
x402 = X402Middleware(
    api_key=os.environ["BLOCKEDEN_API_KEY"],
    facilitator_url="https://x402.blockeden.xyz",
    network="sui",
    token="USDC",
)

@app.get("/api/premium/data")
async def get_premium_data(
    payment: X402Payment = Depends(x402.require(amount="0.01"))
):
    """Protected endpoint requiring 0.01 USDC payment"""
    return {
        "data": "Your premium content here",
        "payment": {
            "tx_hash": payment.tx_hash,
            "amount": payment.amount,
            "network": payment.network,
        }
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Python (Flask)

from flask import Flask, jsonify
from blockeden_x402 import X402Middleware

app = Flask(__name__)

# Configure x402 middleware
x402 = X402Middleware(
    api_key=os.environ["BLOCKEDEN_API_KEY"],
    facilitator_url="https://x402.blockeden.xyz",
    network="sui",
    token="USDC",
)

@app.route('/api/premium/data')
@x402.require(amount="0.01")
def get_premium_data(payment):
    """Protected endpoint requiring 0.01 USDC payment"""
    return jsonify({
        "data": "Your premium content here",
        "payment": {
            "tx_hash": payment.tx_hash,
            "amount": payment.amount,
            "network": payment.network,
        }
    })

if __name__ == '__main__':
    app.run(debug=True, port=8000)

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 BlockEden.xyz 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

TypeScript

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

Python

pip install blockeden-x402-client

Basic Client Setup

TypeScript (Fetch)

import { X402Client } from '@blockeden/x402-client';

// Initialize client with wallet
const client = new X402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'sui',
  facilitatorUrl: 'https://x402.blockeden.xyz',
});

// 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();

TypeScript (Axios)

import axios from 'axios';
import { createX402Interceptor } from '@blockeden/x402-client';

// Create axios instance with x402 interceptor
const api = axios.create({
  baseURL: 'https://api.example.com',
});

// Add x402 payment interceptor
createX402Interceptor(api, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'sui',
  facilitatorUrl: 'https://x402.blockeden.xyz',
});

// Make requests normally - payments handled automatically
async function fetchPremiumData() {
  try {
    const response = await api.get('/api/premium/data');
    console.log('Data:', response.data);
  } catch (error) {
    console.error('Request failed:', error);
  }
}

fetchPremiumData();

Python (httpx)

import os
from blockeden_x402_client import X402Client

# Initialize client with wallet
client = X402Client(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
    network="sui",
    facilitator_url="https://x402.blockeden.xyz",
)

# Fetch protected resource - payment handled automatically
async def fetch_premium_data():
    response = await client.get(
        "https://api.example.com/api/premium/data"
    )

    data = response.json()
    print(f"Data: {data}")
    print(f"Payment TX: {response.headers.get('X-Payment-Response')}")

# Run async function
import asyncio
asyncio.run(fetch_premium_data())

Python (requests)

import os
import requests
from blockeden_x402_client import X402Session

# Create session with x402 support
session = X402Session(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
    network="sui",
    facilitator_url="https://x402.blockeden.xyz",
)

# Make requests normally - payments handled automatically
def fetch_premium_data():
    response = session.get(
        "https://api.example.com/api/premium/data"
    )

    data = response.json()
    print(f"Data: {data}")
    print(f"Payment TX: {response.headers.get('X-Payment-Response')}")

fetch_premium_data()

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 '@blockeden/x402-mcp';

const server = new X402MCPServer({
  wallet: process.env.AGENT_WALLET_PRIVATE_KEY,
  network: 'sui',
  facilitatorUrl: 'https://x402.blockeden.xyz',
  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 blockeden_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.blockeden.xyz",
)

# 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

BlockEden.xyz Facilitator

Facilitator URL: https://x402.blockeden.xyz

Available Endpoints:

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

Environment Variables

# Server configuration
BLOCKEDEN_API_KEY=your_api_key_here
BLOCKEDEN_X402_FACILITATOR=https://x402.blockeden.xyz

# Client configuration
WALLET_PRIVATE_KEY=your_private_key_here
X402_NETWORK=sui

Supported Networks

BlockEden.xyz's x402 facilitator supports the following networks:

Network	Chain ID	Token	Status
Sui Mainnet	sui	USDC	🟢 Primary
Sui Testnet	sui-testnet	USDC	🟢 Active
Base Mainnet	base	USDC	🟡 Coming Soon
Base Sepolia	base-sepolia	USDC	🟡 Coming Soon
Ethereum	ethereum	USDC	🟡 Coming Soon
Polygon	polygon	USDC	🟡 Coming Soon
Avalanche	avalanche	USDC	🟡 Coming Soon
Aptos Mainnet	aptos	USDC	🟡 Coming Soon
Aptos Testnet	aptos-testnet	USDC	🟡 Coming Soon

Sui-First Optimization

BlockEden.xyz prioritizes Sui for the best x402 experience with sub-200ms settlement times and ultra-low costs.

Payment Configuration Options

Server-Side Options

X402Middleware({
  apiKey: 'your_api_key',
  facilitatorUrl: 'https://x402.blockeden.xyz',

  // 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.blockeden.xyz',

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

TypeScript

import { X402Client } from '@blockeden/x402-client';

const client = new X402Client({
  privateKey: process.env.TEST_WALLET_KEY,
  network: 'sui-testnet', // Use testnet
  facilitatorUrl: 'https://x402.blockeden.xyz',
});

// 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());

Python

from blockeden_x402_client import X402Client

client = X402Client(
    private_key=os.environ["TEST_WALLET_KEY"],
    network="sui-testnet",  # Use testnet
    facilitator_url="https://x402.blockeden.xyz",
)

# Test payment flow
response = client.get("http://localhost:8000/api/premium/data")

print(f"Status: {response.status_code}")
print(f"Payment TX: {response.headers.get('X-Payment-Response')}")
print(f"Data: {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 - BlockEden.xyz x402 facilitator service
• Join Discord - Get help from community
• Join Waitlist - Get early access to BlockEden.xyz x402 facilitator

Need Help?

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

---

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