x402-deploy API Reference

Complete API reference for x402-deploy monetization framework.

---

Core Functions

wrapWithX402(app, config)

Wraps an Express application with x402 payment gateway middleware.

Parameters: - app (Express.Application) - Your Express app instance - config (X402Config) - x402 configuration object

Returns: Express.Application - The wrapped application

Example:

import express from 'express';
import { wrapWithX402 } from '@nirholas/universal-crypto-mcp/x402';

const app = express();

app.get('/api/data', (req, res) => {
  res.json({ data: 'premium content' });
});

const wrappedApp = wrapWithX402(app, {
  payment: {
    wallet: '0x...',
    network: 'eip155:42161'
  },
  pricing: {
    routes: {
      'GET /api/data': '$0.001'
    }
  }
});

wrappedApp.listen(3000);

---

createX402Middleware(config)

Creates Express middleware for x402 payment verification.

Parameters: - config (X402Config) - x402 configuration

Returns: RequestHandler - Express middleware function

Example:

import express from 'express';
import { createX402Middleware } from '@nirholas/universal-crypto-mcp/x402';

const app = express();
const x402 = createX402Middleware({
  payment: { wallet: '0x...', network: 'eip155:8453' },
  pricing: { routes: { 'GET /api/*': '$0.001' } }
});

app.use(x402);

app.get('/api/data', (req, res) => {
  // Only executes if payment is valid
  res.json({ data: 'content' });
});

---

createX402McpServer(options)

Creates an MCP server with x402 payment integration.

Parameters: - options (X402McpOptions) - Server configuration - config (X402Config) - x402 configuration - tools (Record) - MCP tool definitions - resources? (Resource[]) - Optional resources - prompts? (Prompt[]) - Optional prompts

Returns: McpServer - Configured MCP server

Example:

import { createX402McpServer } from '@nirholas/universal-crypto-mcp/x402';

const server = createX402McpServer({
  config: {
    payment: {
      wallet: '0x...',
      network: 'eip155:42161'
    },
    pricing: {
      tools: {
        'analyze_sentiment': '$0.01',
        'get_market_data': '$0.001'
      }
    }
  },
  tools: {
    analyze_sentiment: {
      description: 'Analyze crypto sentiment',
      inputSchema: {
        type: 'object',
        properties: {
          symbol: { type: 'string' }
        }
      },
      handler: async ({ symbol }) => {
        const result = await analyzeSentiment(symbol);
        return result;
      }
    }
  }
});

server.listen();

---

verifyPayment(options)

Verifies a payment on-chain.

Parameters: - options (VerifyPaymentOptions) - paymentHeader (string) - Base64-encoded payment proof - expectedPrice (string) - Expected payment amount (e.g., "$0.001") - expectedPayTo (string) - Expected recipient wallet address - network (Network) - Blockchain network identifier - facilitatorUrl? (string) - Optional facilitator endpoint - testMode? (boolean) - Skip verification for testing

Returns: Promise<PaymentVerification>

Example:

import { verifyPayment } from '@nirholas/universal-crypto-mcp/x402';

const verification = await verifyPayment({
  paymentHeader: req.headers['x-payment'],
  expectedPrice: '$0.001',
  expectedPayTo: '0x...',
  network: 'eip155:42161'
});

if (verification.valid) {
  console.log(`Payment from ${verification.payer}`);
  console.log(`Amount: ${verification.amount}`);
  console.log(`Tx: ${verification.txHash}`);
} else {
  console.error(`Invalid: ${verification.error}`);
}

---

Payment Verifier

PaymentVerifier

Class for managing payment verification logic.

Constructor:

new PaymentVerifier(config: PaymentConfig)

Methods:

verify(payment, route)

Verifies a payment for a specific route.

const verifier = new PaymentVerifier({
  wallet: '0x...',
  network: 'eip155:42161'
});

const result = await verifier.verify(
  paymentProof,
  'GET /api/premium'
);

getPendingEscrowBalance(payer)

Gets pending escrow balance for a payer.

const balance = await verifier.getPendingEscrowBalance('0x...');
console.log(`Escrowed: ${balance} USDC`);

---

Pricing Engine

PricingEngine

Dynamic pricing engine with support for flat, tiered, and load-based pricing.

Constructor:

new PricingEngine(pricing: PricingConfig)

Methods:

setDynamicPricing(route, config)

Configure dynamic pricing for a route.

const engine = new PricingEngine({
  'GET /api/data': '$0.01'
});

engine.setDynamicPricing('GET /api/data', {
  basePrice: '$0.01',
  tiers: [
    { minRequests: 0, maxRequests: 100, price: '$0.01' },
    { minRequests: 100, maxRequests: 1000, price: '$0.008' },
    { minRequests: 1000, price: '$0.005' }
  ],
  loadMultiplier: 1.5
});

calculatePrice(route, payer?)

Calculate price for a route, optionally considering payer history.

const price = engine.calculatePrice('GET /api/data', '0x...');
console.log(`Price: ${price}`);

recordPayment(payer, record)

Record a payment for analytics and volume pricing.

engine.recordPayment('0x...', {
  id: 'pay_123',
  payer: '0x...',
  route: 'GET /api/data',
  amount: '1000000',
  asset: 'USDC',
  network: 'eip155:42161',
  timestamp: new Date(),
  settled: true
});

getPayerHistory(payer)

Get payment history for a payer.

const history = engine.getPayerHistory('0x...');
console.log(`Total payments: ${history.length}`);

---

Rate Limiter

RateLimiter

Token bucket rate limiting per payer.

Constructor:

new RateLimiter(config: RateLimitConfig)

Methods:

checkLimit(payer, route?)

Check if a payer is within rate limits.

const limiter = new RateLimiter({
  maxRequests: 100,
  windowSeconds: 3600,
  perPayer: true
});

const result = await limiter.checkLimit('0x...', 'GET /api/data');

if (result.allowed) {
  // Process request
} else {
  res.status(429).json({
    error: 'rate_limit_exceeded',
    retryAfter: result.retryAfter
  });
}

resetLimit(payer)

Reset rate limit for a payer.

await limiter.resetLimit('0x...');

---

Analytics Engine

AnalyticsEngine

Track and analyze payment activity.

Constructor:

new AnalyticsEngine(config: AnalyticsConfig)

Methods:

trackRequest(payer, route, amount)

Track a successful request with payment.

const analytics = new AnalyticsEngine({ enabled: true });

await analytics.trackRequest('0x...', 'GET /api/data', '1000000');

recordPayment(payment)

Record a payment in analytics.

await analytics.recordPayment({
  id: 'pay_123',
  payer: '0x...',
  route: 'GET /api/data',
  amount: '1000000',
  asset: 'USDC',
  network: 'eip155:42161',
  timestamp: new Date(),
  settled: true
});

getAnalytics(period?)

Get analytics summary.

const data = await analytics.getAnalytics('30d');

console.log(`Revenue: ${data.totalRevenue}`);
console.log(`Payments: ${data.totalPayments}`);
console.log(`Unique payers: ${data.uniquePayers.size}`);

---

Discovery Protocol

registerService(metadata)

Register your service in the x402 discovery network.

Parameters: - metadata (ServiceMetadata) - name (string) - Service name - description (string) - Service description - pricing (PricingConfig) - Pricing configuration - categories (string[]) - Service categories - examples? (Example[]) - Usage examples - endpoint (string) - Service URL

Returns: Promise<Registration>

Example:

import { registerService } from '@nirholas/universal-crypto-mcp/x402';

const registration = await registerService({
  name: 'crypto-sentiment-analyzer',
  description: 'Real-time crypto sentiment analysis from social media',
  pricing: {
    'analyze': '$0.01',
    'batch_analyze': '$0.05'
  },
  categories: ['analytics', 'sentiment', 'crypto'],
  examples: [
    {
      prompt: 'Analyze sentiment for BTC',
      response: 'Sentiment: Bullish (85% confidence)'
    }
  ],
  endpoint: 'https://my-service.vercel.app'
});

console.log(`Registered: ${registration.id}`);

---

discoverServices(filters)

Search for services in the discovery network.

Parameters: - filters (DiscoveryFilters) - category? (string) - Filter by category - maxPrice? (string) - Maximum price - minRating? (number) - Minimum rating (0-5) - query? (string) - Search query - limit? (number) - Max results

Returns: Promise<Service[]>

Example:

import { discoverServices } from '@nirholas/universal-crypto-mcp/x402';

const services = await discoverServices({
  category: 'weather',
  maxPrice: '$0.01',
  minRating: 4.0,
  limit: 10
});

for (const service of services) {
  console.log(`${service.name} - ${service.pricing}`);
  console.log(`  ${service.description}`);
  console.log(`  Rating: ${service.rating}/5`);
}

---

Types

X402Config

Main configuration object for x402-deploy.

interface X402Config {
  name: string;
  type?: 'express' | 'next' | 'mcp' | 'fastapi';
  payment: PaymentConfig;
  pricing: {
    default?: string;
    routes?: Record<string, string>;
    tools?: Record<string, string>;
  };
  discovery?: DiscoveryConfig;
  rateLimit?: RateLimitConfig;
  analytics?: AnalyticsConfig;
}

PaymentConfig

Payment configuration.

interface PaymentConfig {
  wallet: `0x${string}`;
  network: Network;
  token?: string;
  facilitator?: string;
  acceptedAssets?: string[];
  escrow?: EscrowConfig;
}

Network

Blockchain network identifier.

type Network = 
  | 'eip155:1'      // Ethereum
  | 'eip155:42161'  // Arbitrum
  | 'eip155:8453'   // Base
  | 'eip155:137'    // Polygon
  | 'eip155:10'     // Optimism
  | 'eip155:84532'  // Base Sepolia
  | string;

PaymentVerification

Result of payment verification.

interface PaymentVerification {
  valid: boolean;
  payer: string;
  amount: string;
  txHash?: string;
  error?: string;
}

PricingTier

Volume-based pricing tier.

interface PricingTier {
  minRequests: number;
  maxRequests?: number;
  price: string;
}

DynamicPricing

Dynamic pricing configuration.

interface DynamicPricing {
  basePrice: string;
  tiers?: PricingTier[];
  loadMultiplier?: number;
  timePricing?: TimePricing;
}

PaymentRecord

Individual payment record.

interface PaymentRecord {
  id: string;
  payer: string;
  route: string;
  amount: string;
  asset: string;
  network: Network;
  txHash?: string;
  timestamp: Date;
  settled: boolean;
}

---

Utilities

parsePrice(price)

Parse a price string to normalized format.

import { parsePrice } from '@nirholas/universal-crypto-mcp/x402';

const { value, currency } = parsePrice('$0.001');
// { value: 0.001, currency: 'USD' }

const { value, currency } = parsePrice('1000000 USDC');
// { value: 1000000, currency: 'USDC' }

formatPrice(value, currency)

Format a price value to string.

import { formatPrice } from '@nirholas/universal-crypto-mcp/x402';

const price = formatPrice(0.001, 'USD');
// '$0.001000'

const price = formatPrice(1000000, 'USDC');
// '1000000 USDC'

priceToX402Format(price, decimals)

Convert price to x402 payment format.

import { priceToX402Format } from '@nirholas/universal-crypto-mcp/x402';

const formatted = priceToX402Format('$0.01', 6);
// { asset: 'USDC', amount: '10000' }

---

Next.js Integration

createX402Middleware(config)

Create Next.js middleware for x402 payments.

Example:

// middleware.ts
import { createX402Middleware } from '@nirholas/universal-crypto-mcp/x402/next';
import config from './x402.config.json';

export const middleware = createX402Middleware(config);

export const config = {
  matcher: '/api/:path*'
};

---

Error Handling

Common Errors

PaymentRequiredError

{
  status: 402,
  error: 'payment_required',
  message: 'Payment required to access this resource',
  payment: {
    price: '$0.001',
    wallet: '0x...',
    network: 'eip155:42161',
    token: 'USDC'
  }
}

PaymentInvalidError

{
  status: 402,
  error: 'payment_invalid',
  message: 'Payment verification failed',
  reason: 'insufficient_amount' | 'wrong_recipient' | 'transaction_not_found'
}

RateLimitError

{
  status: 429,
  error: 'rate_limit_exceeded',
  message: 'Rate limit exceeded',
  retryAfter: 3600,
  limit: 100,
  window: 3600
}

---

Best Practices

1. Error Handling

Always handle payment errors gracefully:

app.get('/api/data', async (req, res) => {
  try {
    const data = await getData();
    res.json(data);
  } catch (error) {
    if (error.status === 402) {
      res.status(402).json({
        error: 'payment_required',
        payment: error.payment
      });
    } else {
      res.status(500).json({ error: 'internal_error' });
    }
  }
});

2. Caching

Cache expensive operations:

import NodeCache from 'node-cache';

const cache = new NodeCache({ stdTTL: 600 });

app.get('/api/data', async (req, res) => {
  const cached = cache.get('data');
  if (cached) return res.json(cached);

  const data = await expensiveOperation();
  cache.set('data', data);
  res.json(data);
});

3. Rate Limiting

Implement rate limiting per payer:

{
  "rateLimit": {
    "enabled": true,
    "maxRequests": 100,
    "windowSeconds": 3600,
    "perPayer": true
  }
}

4. Monitoring

Enable analytics and webhooks:

{
  "analytics": {
    "enabled": true,
    "webhookUrl": "https://myapp.com/webhooks/payment",
    "webhookSecret": "secret",
    "verbose": true
  }
}

---

See Also

• Configuration Guide - Complete configuration reference
• Deployment Guide - Production deployment
• Quick Start - Get started in 5 minutes
• Examples - Code examples