README.md

April 17, 2026 · View on GitHub

x402 Bazaar

The decentralized API marketplace where AI agents pay with USDC, not API keys.

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

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`	Server port (default: 3000)
`NETWORK`	`mainnet` or `testnet`
`WALLET_ADDRESS`	USDC recipient address
`WALLET_ID`	Coinbase CDP wallet ID
`COINBASE_API_KEY`	Coinbase Developer Platform API key
`COINBASE_API_SECRET`	CDP API secret
`SUPABASE_URL`	Supabase project URL
`SUPABASE_KEY`	Supabase anon key
`OPENAI_API_KEY`	OpenAI key (for /api/image, /api/summarize, /api/sentiment)
`ADMIN_TOKEN`	Secret token for dashboard access
`TELEGRAM_BOT_TOKEN`	Telegram bot token for monitoring alerts + interactive commands
`TELEGRAM_CHAT_ID`	Telegram chat ID to receive notifications

Scripts

npm start            # Start the server
npm run mcp          # Start the MCP server
npm run seed         # Seed 112+ services into Supabase
npm run seed:wrappers # Register the 112 native wrappers
npm run demo         # Run the autonomous agent demo
npm run demo:live    # Live demo with terminal UI

Security

Helmet -- Security headers (HSTS, X-Content-Type, X-Frame-Options)
CORS -- Strict origin whitelist (no wildcards in production)
Rate Limiting -- 3 tiers: general (500/15min), paid endpoints (30/min), registration (10/hr)
Anti-Replay -- Transaction hashes persisted in Supabase used_transactions table
On-Chain Verification -- Validates USDC transfer logs directly via RPC
USDC-Only -- Rejects non-USDC token transfers
Input Sanitization -- Control character rejection, Postgres LIKE escaping, length limits
SSRF Protection -- Blocks localhost, private IPs, IPv6 loopback, cloud metadata
Body Limit -- 10KB max request body
RPC Timeout -- 10s timeout on all blockchain calls

Create Your Own x402 API

Monetize any Python function in 5 minutes with the FastAPI template:

git clone https://github.com/Wintyx57/x402-fast-monetization-template
cd x402-fast-monetization-template
pip install -r requirements.txt
cp .env.example .env  # Set your WALLET_ADDRESS
python main.py

@x402_paywall(price=0.05, description="My API", tags=["cool"])
def my_function(text: str) -> dict:
    return {"result": "something"}

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a PR.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT