MonX402

HTTP 402 Payment Protocol Implementation for Monad

MonX402 is a TypeScript SDK implementing the HTTP 402 Payment Required standard on Monad blockchain. It enables API monetization through cryptocurrency micropayments, leveraging Monad's high throughput (10,000 TPS) and 1-second finality for real-time payment settlement.

Features

• 1-Second Finality - Payments settle in under 1 second on Monad
• EVM Compatible - Built on ethers.js, works with existing Ethereum tooling
• Autonomous Payments - Designed for AI agents and machine-to-machine transactions
• Axios-Compatible Client - Drop-in replacement for standard HTTP clients
• Client-Side Signing - Private keys never leave the user's machine
• AI Crawler Monetization - Get paid when AI companies crawl your website
• Universal Bot Protection - Block ALL bots (scrapers, crawlers, etc.) without payment
• Production Ready - Comprehensive error handling and transaction monitoring

Use Cases

MonX402 is designed for scenarios requiring high-frequency, low-cost API payments:

• AI Agent Marketplaces - Autonomous agents paying for API access without human intervention
• High-Frequency Trading APIs - Real-time market data with per-request pricing
• API Monetization - Convert any Next.js API route into a paid service
• Microservices Architecture - Internal API billing between services
• Pay-Per-Use Infrastructure - Charge for actual usage rather than subscriptions

Installation

npm install monad-x402

Quick Start

Client Usage

The SDK provides an Axios-compatible client that handles payment flows automatically:

import { x402axios } from 'monad-x402';

const response = await x402axios.get('https://api.example.com/premium/data', {
  privateKey: process.env.MONAD_PRIVATE_KEY
});

console.log(response.data);
console.log('Transaction hash:', response.paymentInfo?.transactionHash);

Server Setup

Add payment protection to your Next.js API routes using middleware:

// middleware.ts
import { paymentMiddleware } from 'monad-x402';

export const middleware = paymentMiddleware(
  process.env.PAYMENT_RECIPIENT_ADDRESS,
  {
    '/api/premium/crypto-prices': {
      price: '1000000000000000',  // 0.001 MON
      network: 'testnet'
    }
  },
  { url: process.env.FACILITATOR_URL }
);

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

Your API route remains unchanged - the middleware handles all payment logic:

// app/api/premium/crypto-prices/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const response = await fetch(
    'https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd'
  );
  const data = await response.json();
  
  return NextResponse.json({
    bitcoin: data.bitcoin.usd,
    ethereum: data.ethereum.usd
  });
}

AI Crawler Monetization

Get paid when AI companies crawl your website:

// middleware.ts
import { aiCrawlerMiddleware } from 'monad-x402';

export const middleware = aiCrawlerMiddleware({
  enabled: true,
  price: '1000000000000000',  // 0.001 MON per page
  recipientAddress: process.env.PAYMENT_RECIPIENT_ADDRESS,
  network: 'testnet'
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']  
};

Detects and charges AI crawlers (GPTBot, Claude, Google-Extended, etc.) while allowing regular users free access.

Universal Bot Protection

Block ALL bots - scrapers, crawlers, headless browsers, and automated tools:

// middleware.ts
import { blockAllBotsExceptSEO } from 'monad-x402';

// Allow search engines for SEO, charge everything else
export const middleware = blockAllBotsExceptSEO(
  process.env.PAYMENT_RECIPIENT_ADDRESS,
  '1000000000000000'  // 0.001 MON
);

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']  
};

Detects and blocks:

• Search engines - Googlebot, Bingbot, Baidu, Yandex
• AI crawlers - GPT, Claude, Gemini, Perplexity
• Scrapers - Scrapy, cURL, Wget, Python Requests
• SEO tools - Ahrefs, Semrush, Screaming Frog
• Headless browsers - Puppeteer, Playwright, Selenium
• Any automated tool - Pattern + behavioral detection

Architecture

┌─────────────┐                    ┌─────────────┐
│   Buyer     │                    │   Seller    │
│  (Client)   │                    │  (API)      │
└──────┬──────┘                    └──────┬──────┘
       │                                  │
       │  1. GET /api/premium/data       │
       │─────────────────────────────────>│
       │                                  │
       │  2. 402 Payment Required         │
       │<─────────────────────────────────│
       │     (payment requirements)       │
       │                                  │
       │  3. Build & Sign Transaction     │
       │     (client-side, secure)        │
       │                                  │
       │  4. GET with X-PAYMENT header    │
       │─────────────────────────────────>│
       │                                  │
       │              ┌──────────────┐    │
       │              │ Facilitator  │    │
       │              │   Service    │    │
       │              └──────┬───────┘    │
       │                     │            │
       │  5. Verify Payment  │            │
       │     ────────────────>            │
       │     <────────────────            │
       │                     │            │
       │  6. Return Data     │            │
       │<─────────────────────────────────│
       │                     │            │
       │  7. Settle on Chain │            │
       │     ────────────────>            │
       │                     ▼            │
       │              ┌──────────────┐    │
       │              │    Monad     │    │
       │              │  Blockchain  │    │
       │              └──────────────┘    │

Configuration

Environment Variables

# Client
MONAD_PRIVATE_KEY=0x...

# Server
PAYMENT_RECIPIENT_ADDRESS=0x...
MONAD_NETWORK=testnet
FACILITATOR_URL=http://localhost:3000/api/facilitator

Network Configuration

import { createMonadProvider } from 'monad-x402';

const provider = createMonadProvider('testnet');

API Reference

Client API

const response = await x402axios.get(url, {
  privateKey: string,
  headers?: Record<string, string>,
  timeout?: number
});

response.paymentInfo = {
  transactionHash: string,
  amount: string,
  recipient: string,
  network: string
};

Middleware API

interface RouteConfig {
  price: string;           // Amount in wei
  network: 'testnet' | 'mainnet';
  config?: {
    description?: string;
    mimeType?: string;
    maxTimeoutSeconds?: number;
  };
}

Utility Functions

import {
  createMonadWallet,
  buildTransferTransaction,
  signTransaction,
  submitTransaction,
  formatMON,
  parseMON,
  getBalance
} from 'monad-x402';

Development

npm run demo          # Run demo
npm run build:sdk     # Build SDK
npm run build         # Build all

Monad Testnet

• RPC: https://testnet-rpc.monad.xyz
• Chain ID: 10143
• Explorer: https://testnet-explorer.monad.xyz

Security

Private keys are signed client-side and never transmitted over the network. The implementation uses ethers.js for transaction signing and is fully open source.

Contributing

Contributions are welcome. Please submit pull requests or open issues on GitHub.

License

MIT License - see LICENSE file for details.

Links

• Monad
• x402 Protocol Specification
• Documentation

Roadmap

• Mainnet support
• ERC-20 token payments
• Batch payment support
• Payment streaming
• Multi-language SDK support