x402-backend

<p align="center"> <h1 align="center">x402 Bazaar</h1> <p align="center"> <strong>The decentralized API marketplace where AI agents pay with USDC, not API keys.</strong> </p> <p align="center"> <a href="https://x402bazaar.org"><img src="https://img.shields.io/badge/website-x402bazaar.org-blue?style=flat-square" alt="Website"></a> <a href="https://www.npmjs.com/package/x402-bazaar"><img src="https://img.shields.io/npm/v/x402-bazaar?style=flat-square&color=green" alt="npm"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="License"></a> <a href="https://github.com/Wintyx57/x402-backend"><img src="https://img.shields.io/github/stars/Wintyx57/x402-backend?style=flat-square" alt="Stars"></a> <a href="https://basescan.org"><img src="https://img.shields.io/badge/chain-Base%20%2B%20SKALE%20%2B%20Polygon-8b5cf6?style=flat-square" alt="Chain"></a> </p> </p>

---

Ecosystem

| Repository | Description | |------------|-------------| | x402-backend (this repo) | Backend API — Express server, payment middleware, 69 native wrappers + 43 marketplace services, MCP server | | x402-frontend | React frontend — 15 pages, glassmorphism UI, wallet connect, i18n FR/EN | | x402-langchain | Python package — LangChain tools for x402 Bazaar (pip install) | | x402-fast-monetization-template | FastAPI template — Monetize any Python function with x402 in 5 minutes | | CLI: npx x402-bazaar | One-line setup for Claude Desktop, Cursor, VS Code | | @x402/sdk | TypeScript SDK — typed client for x402 Bazaar APIs | | Reviews API | Ratings & reviews system for marketplace services | | Bazaar Discovery | Agent discovery via @x402/extensions v2.5.0 (official Coinbase SDK) |

Live: x402bazaar.org | API: x402-api.onrender.com | Dashboard: x402-api.onrender.com/dashboard

---

What is x402 Bazaar?

x402 Bazaar is an autonomous API marketplace built on the HTTP 402 Payment Required standard. AI agents discover services, pay in USDC on Base, SKALE on Base (ultra-low gas), or Polygon, and get instant access -- no API keys, no subscriptions, no accounts. The server verifies payments on-chain and enforces anti-replay protection, making every transaction trustless and permissionless.

Key Features

• HTTP 402 Protocol -- Standard-compliant payment flow. Call an endpoint, get a 402 with payment details, pay USDC, retry with tx hash, done.
• 69 Native API Wrappers -- Web search, URL scraper, Twitter/X, weather, crypto, jokes, DALL-E 3, translation, code execution, sentiment analysis, and 50+ more -- all behind micropayments.
• 43+ Marketplace Services -- Growing catalog of third-party APIs monetized through x402 (total: 112+ callable endpoints).
• LangChain + Python SDK -- pip install x402-bazaar for agents built with LangChain/LangGraph/CrewAI.
• Multi-Chain -- Base (mainnet) + SKALE on Base (ultra-low gas ~$0.0007/tx) + Polygon (EIP-3009 gas-free).
• MCP Server (v2.7.0, 15 tools) -- Plug into Claude Desktop, Cursor, VS Code, or Claude Code.
• One-Line Setup -- npx x402-bazaar init detects your IDE and configures everything.
• Anti-Replay Protection -- Every transaction hash is stored in Supabase and can only be used once.
• Budget Control -- Per-session spending caps for AI agents (configurable MAX_BUDGET_USDC).
• Security Hardened -- Helmet headers, CORS whitelist, rate limiting (3 tiers), input sanitization, SSRF protection, httpOnly admin sessions, HMAC'd IP hashing.
• 2136 Tests -- 398 suites, all passing (node:test, zero deps).
• Real-Time Monitoring -- 69 native endpoints checked every 5min, Telegram alerts on transitions, public /api/status page.
• Telegram Bot -- Interactive admin bot with 6 commands (/balance, /stats, /status, /recent, /services, /help).
• Auto-Test on Registration -- New services are pinged automatically, with Telegram notification on result.
• Public Stats -- GET /api/public-stats (no auth) for frontend homepage counters.

Quick Start

# One-line setup for AI IDEs (Claude Desktop, Cursor, VS Code)
npx x402-bazaar init

Or run the server locally:

git clone https://github.com/Wintyx57/x402-backend.git
cd x402-backend
npm install
cp .env.example .env   # Fill in your keys
node server.js

How the x402 Payment Flow Works

Agent                          x402 Bazaar                     Base / SKALE / Polygon
  |                                |                                |
  |  GET /api/weather?city=Paris   |                                |
  |------------------------------->|                                |
  |  402 Payment Required          |                                |
  |  { amount: 0.02, recipient }   |                                |
  |<-------------------------------|                                |
  |                                |                                |
  |  Transfer 0.02 USDC ------------------------------------------>|
  |  tx: 0xabc123...              |                                |
  |                                |                                |
  |  GET /api/weather?city=Paris   |                                |
  |  X-Payment-TxHash: 0xabc123   |                                |
  |------------------------------->|                                |
  |                                |  verify tx on-chain ---------->|
  |                                |  mark tx used (anti-replay)    |
  |  200 OK { temperature: 15.2 } |                                |
  |<-------------------------------|                                |

API Reference

Marketplace Endpoints

| Route | Method | Cost | Description | |-------|--------|------|-------------| | / | GET | Free | Marketplace info + endpoint catalog | | /health | GET | Free | Health check + supported networks | | /services | GET | Free | List all registered services (paginated) | | /search?q= | GET | Free | Search services by keyword | | /register | POST | 1.00 USDC | Register a new service |

Native API Wrappers (69 endpoints, x402-powered)

| Route | Cost | Source | Description | |-------|------|--------|-------------| | /api/search?q= | 0.005 USDC | DuckDuckGo | Clean web search results for LLMs | | /api/scrape?url= | 0.005 USDC | Cheerio + Turndown | Any URL to clean Markdown | | /api/twitter?user=\|tweet=\|search= | 0.005 USDC | fxtwitter | Twitter/X profiles, tweets, search | | /api/weather?city= | 0.02 USDC | Open-Meteo | Weather data for any city | | /api/crypto?coin= | 0.02 USDC | CoinGecko | Cryptocurrency prices (USD/EUR) | | /api/joke | 0.01 USDC | Official Joke API | Random joke | | /api/image?prompt= | 0.05 USDC | DALL-E 3 | AI image generation (1024x1024) | | /api/wikipedia?q= | 0.005 USDC | Wikipedia API | Article summaries | | /api/dictionary?word= | 0.005 USDC | Free Dictionary | English definitions | | /api/countries?name= | 0.005 USDC | REST Countries | Country data | | /api/github?user=\|repo= | 0.005 USDC | GitHub API | Profiles and repo stats | | /api/npm?package= | 0.005 USDC | NPM Registry | Package metadata | | /api/ip?address= | 0.005 USDC | ip-api.com | IP geolocation | | /api/translate?text=&to= | 0.005 USDC | MyMemory | Translate 90+ languages | | /api/summarize?text= | 0.01 USDC | GPT-4o-mini | AI text summarization | | /api/code | 0.005 USDC | Piston API | Execute code in 50+ languages | | /api/sentiment?text= | 0.005 USDC | GPT-4o-mini | Sentiment analysis | | /api/dns?domain= | 0.003 USDC | Node DNS | DNS record lookup | | /api/currency?from=&to= | 0.005 USDC | Frankfurter | Currency conversion (ECB) | | ...and 22 more | 0.003-0.005 | Various | See API_WRAPPERS.md |

Monitoring & Status (Free)

| Route | Description | |-------|-------------| | /api/status | Live monitoring status for all 69 native endpoints | | /api/status/uptime | Uptime percentages by endpoint | | /api/status/history | Check history (last 24h) | | /api/public-stats | Public stats (services, API calls, monitoring, integrations) |

Dashboard (Admin, requires X-Admin-Token)

| Route | Description | |-------|-------------| | /dashboard | Admin UI -- stats, services, activity log, System Info | | /api/stats | JSON stats (services, payments, revenue, wallet balance) | | /api/analytics | Enriched analytics (balance, recent activity, avg price) |

Payment Headers

| Header | Required | Description | |--------|----------|-------------| | X-Payment-TxHash | Yes (for paid endpoints) | USDC transfer transaction hash | | X-Payment-Chain | No (default: base) | Chain used: base, base-sepolia, skale, or polygon |

MCP Server

The MCP server exposes x402 Bazaar as native tools for AI IDEs. Agents can discover, search, and pay for APIs directly from their conversation.

npx x402-bazaar init   # Auto-detects your IDE and installs

MCP Tools (15 total)

| Tool | Cost | Description | |------|------|-------------| | discover_marketplace | Free | Browse available endpoints and service count | | search_services | Free | Search APIs by keyword | | list_services | Free | Full service catalog | | get_service_schema | Free | Inspect required parameters for a service | | find_tool_for_task | Free | Describe what you need in plain English, get the best match | | call_service | price_usdc | Call a marketplace service with auto-payment | | call_api | Free | Call any external API URL | | get_wallet_balance | Free | Check agent wallet USDC balance on-chain | | setup_wallet | Free | Configure or create an agent wallet | | export_private_key | Free | Export the agent wallet private key | | import_openapi | Free | Import an OpenAPI spec as a marketplace service | | import_rapidapi | Free | Import a RapidAPI service to the marketplace | | create_payment_link | Free | Create a payment link for a service | | access_payment_link | Free | Access a payment link | | get_budget_status | Free | Session spending tracker |

Supported Networks

| Network | Chain ID | Gas | USDC Contract | |---------|----------|-----|---------------| | Base | 8453 | ~$0.001 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | Base Sepolia | 84532 | Free (testnet) | 0x036CbD53842c5426634e7929541eC2318f3dCF7e | | SKALE on Base | 1187947933 | ~$0.0007 (CREDITS) | 0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20 | | Polygon | 137 | ~$0.001 (MATIC) | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |

Tech Stack

| Layer | Technology | |-------|-----------| | Runtime | Node.js | | Framework | Express 5 | | Blockchain | Base + SKALE on Base + Polygon (USDC) | | Wallet SDK | Coinbase Developer Platform (CDP) | | Database | Supabase (PostgreSQL) | | MCP | Model Context Protocol SDK | | AI (demo) | OpenAI GPT-4o-mini | | Scraping | Cheerio + Turndown |

Environment Variables

| Variable | Description | |----------|-------------| | PORT