Agent402 Client

What makes it different: Agent402 is open-source and self-hostable — and a single integration gives a buyer three free primitives over the whole x402 ecosystem:

• Find — /api/find?q={task} resolves a task description to the best-matching tools (route, price, schema, ready example).
• Route — POST /api/route is the neutral Smart Order Router: rank tools across every x402 seller crawled (auto-discovered from the Coinbase CDP Bazaar), health-aware, with include=external to exclude us.
• Leaderboard — GET /api/leaderboard is the public on-chain ranking of every x402 seller by Base USDC settled volume — calls served, totalUsd, unique buyers per seller. Pipeline: Bazaar → eth_getLogs → per-call ceiling → aggregate by payTo. Hourly snapshot.

Plus the catalog — 500+ strong: 400+ tools + 100 curated skill packs (multi-tool workflows callable as MCP prompts) — all runnable yourself, plus agent402-tollbooth — an open pay-per-crawl gate for the other side of x402.

Live npm npm npm CI License: MIT

Framework adapters (drop-in tools for the major agent stacks — auto-payment underneath): npm npm npm npm npm npm npm npm

500+ strong — 400+ ready-to-use web tools + 100 multi-tool skill packs for your AI agent, from one server. Every one tested, priced, and settled on-chain; every one earns its place. Browser rendering, web search, PDFs, images, OCR, live financial/crypto/macro data, SEC EDGAR, deterministic stats, forecasting, and options/bond pricing (Black-Scholes, YTM), compression, and 216 pure-CPU utilities. Run it yourself for free in 30 seconds (MCP or plain HTTP, no API keys, no signup), connect it to Claude/ChatGPT/any MCP client, and add your own tools in a few lines. Every tool is deterministic — no LLM in the serving path — and re-tested against its own example before every release.

Optionally, the same server can charge per call over the x402 protocol (USDC on Base, Solana, Polygon, Arbitrum, Monad, Stellar & Algorand, plus USDG on Robinhood Chain — 8 chains) — so the instance you self-host for free can also be a hosted, monetized one. That part is opt-in; by default everything runs free.

🟢 Hosted demo: agent402.tools · 📖 Wiki · 📦 npm · 🔌 MCP Registry

Run it yourself in 30 seconds

Pick whichever fits — all three are free and need no wallet:

1. Zero install — add the hosted connector to Claude (claude.ai → Settings → Connectors → Add custom connector):

https://agent402.tools/mcp

2. One command — run the MCP server locally (the pure-CPU tools work with no key; it pays the tiny proof-of-work for you):

npx -y agent402-mcp
# in Claude Code:  claude mcp add agent402 -- npx -y agent402-mcp

3. Clone and host the whole thing (all 500+ tools as an HTTP API + MCP, free mode, no payments):

git clone https://github.com/MikeyPetrillo/Agent402 && cd Agent402
npm install
FREE_MODE=true npm start          # → http://localhost:3000  (HTTP API + /mcp)

# try a tool over HTTP — no auth in free mode
curl -s -X POST localhost:3000/api/hash -H 'content-type: application/json' \
  -d '{"text":"hello world","algo":"sha256"}'

4. One-click deploy to Railway (full self-hosted instance — adds optional Postgres + Redis plugins for analytics + response caching):

Deploy on Railway

Boots straight from the repo's railway.toml + Dockerfile. Optional plugins are auto-detected via env: add Redis → REDIS_URL enables the upstream response cache (X-Cache: hit|miss), add Postgres → DATABASE_URL enables the public /api/analytics dashboard and the tollbooth waitlist. No env vars required to boot in free mode.

What's in the catalog (500+ tools)

Every tool earns its place: deterministic, tested against its own example on every CI run, priced to market, settled on-chain. CI holds a 400-entry catalog floor and verifies the “500+” claim against the running catalog (scripts/sync-count.js --check). The catalog grows only when a tool is worth calling.

	Examples
Browser & web	render (headless Chromium, executes JS), screenshot, extract (article→markdown), meta
Live search & answers	search (real web index), answer (web answer with citations), depth/news/images variants, suggest
PDFs & media	pdf-to-markdown, pdf-merge/extract-pages/rotate, images-to-pdf, audio-convert, audio-normalize (EBU R128, real ffmpeg)
Images	image-resize, image-convert, image-thumbnail, barcode-decode (jimp/zxing, pure-CPU)
OCR	ocr-image (text out of any image — pure-CPU, no model)
Geo	geo-distance, geo-bbox, geo-bearing, geo-geohash (vincenty / haversine — deterministic)
Live data	fx-rate (ECB), barcode-lookup (Open Food Facts), gov-data (data.gov), weather-forecast/weather-alerts, earthquakes (USGS)
Finance & crypto	stock-quote/stock-history/stock-earnings (Yahoo), crypto-price/crypto-market/crypto-history/crypto-trending/crypto-global (CoinGecko)
Macro (FRED + more)	yield curve, treasury, fiscal, Fed funds, CPI, unemployment, Sahm rule, ECB FX, World Bank, FRED bulk release observations
SEC EDGAR	ticker→CIK, filing list, 10-K/10-Q text, XBRL frames, insider transactions, 13F holdings, IPO calendar, full-text search
Network truth	dns, tls-cert, whois, http-check, robots-check, email-validate, ip-info
Crypto & payments	usdc-balance, tx-status, gas-estimate, ens-resolve, x402-quote/verify, transfer-authorization — non-custodial, multi-chain (Base/Polygon/Arbitrum/Optimism/Ethereum)
Agent memory	wallet-keyed KV + TTL, atomic counters, cross-wallet grants, hash-chained audit log, similarity recall
Stats & forecasting	stats-summary, stats-correlation, linear-regression, moving-average, outliers; forecast-naive/ses/holt/holt-winters + forecast-eval (MAPE/RMSE backtest)
Finance math	black-scholes (option pricing + greeks), bond-price/bond-ytm, cagr, sharpe-ratio, annuity, npv/irr, compound-interest, loan-payment/amortization, break-even, effective-annual-rate (pure-CPU, deterministic)
Compression	gzip/gunzip, brotli-compress/decompress, compress-compare (algorithm shootout, pure-CPU via node:zlib)
HTML extraction	html-select (CSS query), html-table, html-strip, html-links, html-meta — deterministic counterpart to extract
Network ops	dns-lookup, dns-propagation, spf/dmarc/dkim checks, email-deliverability; cert-transparency, http-headers (security audit), tech-stack, asn-info (IP geo)
216 pure-CPU utilities	hashing, JWT, base58, JSON⇄CSV/YAML, token-count, text-chunk, json-validate, text stats, cron math, validators, unit conversions across 13 categories (one parametric tool)

Full schemas live in /openapi.json; a machine-readable catalog is at /api/pricing and /llms.txt. Don't know which tool you need? /api/find?q= resolves a task description to the right tool — route, price, schema, and a ready example — so an agent skips the token-heavy "search around to find a tool" step.

OpenAI-compatible LLM gateway (/v1) — chat, embeddings & images, pay per call

Point any OpenAI SDK at base_url = https://agent402.tools/v1 and pay per call in USDC over x402 — no API key, no signup, no account:

Endpoint	Price	Serves
POST /v1/nano/chat/completions	$0.003	nano models — priced for high-frequency agent loops
POST /v1/auto/chat/completions	$0.01	no model needed — deterministic eval-ranked routing (code / reasoning / long / general), optional quality: fast | balanced | best at the same price, decision disclosed via agent402_router
POST /v1/chat/completions	$0.02	budget/mid models (gpt-4o-mini, claude haiku, gemini flash, deepseek, llama…)
POST /v1/pro/chat/completions	$0.10	mid-frontier (gpt-4o, gpt-4.1, claude sonnet, gemini pro, grok)
POST /v1/premium/chat/completions	$0.50	frontier (gpt-5, o3/o4, claude opus)
POST /v1/embeddings	$0.002	OpenAI embeddings, batch up to 64 inputs — identical repeats are free (deterministic output, cache default-on)
POST /v1/images/generations	$0.08	image generation (Gemini 2.5 Flash Image) — OpenAI images wire, inline base64 out

Streaming (stream: true), full tools/function-calling passthrough, an opt-in prompt cache on the chat tiers (cache: true → byte-identical repeats free for 10 minutes), upstream failover chains that end in a canary-proven model, and a free GET /v1/models listing every model with its tier and caps. A real-money canary buys from every one of these surfaces daily — streaming, routing disclosure, and both cache behaviors included.

Two companion tools close the loop: POST /api/route/execute ($0.01) resolves a task description to the best catalog tool and runs it in one paid call, and POST /api/my-usage ($0.005) returns the paying wallet's own purchase history — no wallet parameter; the x402 payment is the identity, so nobody can read another wallet's profile.

Skill packs — 100 multi-tool workflows

For jobs that span several tools — "audit a domain", "diagnose deliverability", "work up a time-series", "peel an opaque blob" — Agent402 ships curated skill packs: ordered, typed sequences of tool calls with a Claude-ready prompt template. Callable as MCP prompts (prompts/list → prompts/get { name, arguments }) or plain HTTP at /api/skill-packs/{slug}/prompt. A task-shaped query to search_tools returns the matching pack alongside individual tools.

Featured pack	Chains	Use it for
security-audit	dns · dmarc · spf · dkim · cert-transparency · http-headers · tech-stack	Domain security posture
trend-analysis	stock-history · fred-series · stats-summary · moving-average · linear-regression · outliers · correlation · forecast-eval	Quant workup on any time series
structured-scrape	extract · render · html-select · html-table · html-strip · html-links · html-meta	Deterministic scraping decision tree
decode-blob	jwt-decode · gunzip · brotli-decompress · base64 · hex · json-format · hash	Identify and peel any opaque string
forecasting-bake-off	forecast-naive · ses · holt · holt-winters · forecast-eval	Rank 4 forecasters by RMSE, pick the winner
document-intel	pdf-info · pdf-extract · image-ocr · barcode-decode · pdf-merge	PDF/OCR/barcode pipeline
status-snapshot	dns · http-check · http-headers · tls-cert · robots	One-shot service-health sweep
webhook-debug	json-format · jwt-decode · hmac-verify · json-schema-validate · time-render · redact · extract-entities	Triage a webhook payload

All 100 packs at /skills · JSON index at /api/skill-packs.json · on MCP the packs appear under prompts/list so any MCP-aware client picks them up automatically.

x402 Index — Find · Route · Leaderboard

Agent402 is also the open routing + ranking layer for the whole x402 ecosystem: it crawls public x402 sellers (the local catalog + an auto-discovered set from the Coinbase CDP Bazaar, refreshed hourly) and exposes them through three free surfaces — same logic as /api/find: discovery primitives shouldn't cost money.

Surface	What
GET /api/find?q={task}	Resolve a task to the best-matching tools (route, price, schema, ready example)
POST /api/route	Smart Order Router: { query, top, include } → ranked tools across sellers (match score, then health, then price). include=external excludes Agent402 itself
GET /api/leaderboard	On-chain ranking of every x402 seller by Base USDC settled volume (callsSettled, totalUsd, uniqueBuyers per seller). Pipeline: Bazaar → eth_getLogs → per-call ceiling → aggregate. Hourly snapshot
/index	Public HTML dashboard: every seller, tool count, network, last-fetched, rolling health
GET /api/index	JSON snapshot of the same data (totals, per-seller health/routable flags)
/stellar · /algorand	Per-chain marketplace pages: sellers and tools settling on that rail specifically

# "I need an OCR tool — find me the cheapest healthy one anywhere on x402"
curl -X POST https://agent402.tools/api/route \
  -H 'content-type: application/json' \
  -d '{"query":"ocr image to text","top":5}'

# "Who are the most-used x402 sellers right now? (on-chain proof, not self-reports)"
curl 'https://agent402.tools/api/leaderboard?top=25&include=external'

Health-aware: sellers whose last few crawls errored are excluded from the router (a buyer routed to a dead seller wastes money). Healthier sellers also break ties at equal match score and price, so flaky-but-cheap sellers lose to reliable ones. Brand-new sellers (no history yet) get the benefit of the doubt.

Operators get 3-rail attribution on the dashboard (/api/stats, /__operator): USDC vs. proof-of-work vs. heartbeat-probe traffic are counted separately — and the heartbeat rail is gated on a POW_SECRET-signed token (not a spoofable User-Agent), so the operator view reflects real external demand.

For API sellers: /sell is the front door — list an existing x402-speaking API on the index for free with POST /api/index/register (health-routed, 0% take, self-serve, no signup), or install agent402-tollbooth to put a pay-per-crawl gate in front of a site that isn't x402-native yet.

From code, the agent402-client npm package wraps all of this — find() a tool, then call() it, paying automatically (a built-in proof-of-work for free tools, your x402 wallet for paid ones), with caching and idempotent retries:

npm install agent402-client

import { Agent402 } from "agent402-client";
const a = new Agent402();                       // free tier (proof-of-work)
const out = await a.call("hash", { text: "hello world", algo: "sha256" });

Plug into your agent framework (zero-dep adapters)

If you're already on OpenAI / Anthropic / Vercel AI SDK / LangChain / LlamaIndex, skip the wiring — there's a drop-in package that turns the Agent402 catalog into native tool objects for your framework, with payment handled underneath (proof-of-work for free tools, x402+USDC when you pass an @x402/fetch):

Stack	npm	Returns
OpenAI function-calling (chat.completions / Assistants v2 / Responses)	agent402-openai-tools	tools[] for tools: param
Anthropic Messages API (tool_use)	agent402-anthropic-tools	tools[] for tools: param
Vercel AI SDK (streamText / generateText)	agent402-ai-sdk	Record<name, tool()>
LangChain JS / LangGraph	agent402-langchain	DynamicStructuredTool[]
LlamaIndex TS	agent402-llamaindex	FunctionTool[]
Strands Agents (AWS Bedrock AgentCore)	agent402-strands	StrandsTool[] for new Agent({ tools })
Google ADK (Agent Development Kit)	agent402-google-adk	FunctionTool[] for ADK agents
OpenAI Agents SDK	agent402-openai-agents	Agent tools for @openai/agents

// e.g. OpenAI — every adapter has the same surface.
import OpenAI from "openai";
import { agent402Tools } from "agent402-openai-tools";

const openai = new OpenAI();
const { tools, execute } = await agent402Tools({ slugs: ["extract", "hash", "render"] });
const res = await openai.chat.completions.create({ model: "gpt-4o-mini", tools, messages: [...] });
// when the model returns a tool call: await execute(call.function.name, JSON.parse(call.function.arguments));

Already a Claude/MCP user? agent402-mcp is still the better path — paste https://agent402.tools/mcp into your client. The adapters are for direct API integrations where MCP isn't available. Sources: adapters/.

OpenClaw agents: drop in skills/openclaw/agent402/SKILL.md — teaches an OpenClaw agent to find, pay (x402 USDC on Base, seven other chains accepted, or free proof-of-work), and call any of the 400 tools (or 100 packs).

Add your own tool (~15 lines)

A tool is just an object in a kit array. Drop this into any file in src/tools/ (e.g. append to AGENT_TOOLS in src/tools/agent-kit.js) and it's live — routed, schema-published, MCP-exposed, and covered by the "every tool answers its own example" CI check:

{
  route: "POST /api/reverse",
  name: "Reverse text",
  slug: "reverse",
  category: "text",
  price: "$0.001",                       // free via proof-of-work for pure-CPU tools
  description: "Reverse a string. Example: {\"text\":\"abc\"} → {\"reversed\":\"cba\"}",
  discovery: {
    inputSchema: { properties: { text: { type: "string" } }, required: ["text"] },
    example: { text: "abc" },            // CI calls this and checks it works
  },
  handler: (input) => {
    if (typeof input.text !== "string") { const e = new Error('"text" required'); e.statusCode = 400; throw e; }
    return { reversed: [...input.text].reverse().join("") };
  },
}

That's the whole contract: handler(input) returns a JSON-serializable object (or throws an Error with .statusCode for a 4xx). Pure-CPU tools are automatically free-via-proof-of-work; tools that hit the network or disk stay wallet-only. See CONTRIBUTING.md for the full walkthrough.

Optional: charge per call with x402

The same server can require payment per call — useful if you host a public instance. It's off by default (FREE_MODE=true); to enable, set WALLET_ADDRESS

• CDP facilitator keys (free at portal.cdp.coinbase.com) and agents pay in USDC on Base (or Solana, Polygon, Arbitrum, Monad, Stellar, Algorand — or USDG on Robinhood Chain via PAYMENT_NETWORKS=…,robinhood + ROBINHOOD_FACILITATOR_URL) via standard x402 clients:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);
const res = await payFetch("https://agent402.tools/api/extract", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/article" }),
});

Agents without a wallet still use every pure-CPU tool by solving a single-use sha256 proof-of-work (sub-second; the MCP servers do it automatically). Details: wiki: Paying with x402 · Paying with Compute.

Why it's solid

• Everything is tested — CI calls all 500+ tools with their own documented examples and blocks the release on any failure; a production heartbeat checks the live instance every 15 minutes.
• Hardened — connect-time SSRF guard on every URL tool (DNS-rebind safe), proof-of-work that's signed/single-use/slug-scoped, per-IP rate limits, and security headers. See wiki: Security Model.
• Deterministic — no model in the serving path, so the same input always gives the same output, with full OpenAPI schemas.
• Auditable, on-chain revenue — every paid call settles in USDC to agent402.base.eth (a Base name resolving to the public receiving wallet) — verifiable by anyone on Basescan; live counts at /api/stats.
• MIT licensed, fork-friendly — clone it, strip what you don't need, add what you do.

Agent402 in the x402 ecosystem

x402 is an open payment protocol built on HTTP 402 Payment Required for machine-to-machine, pay-per-call payments in stablecoins (USDC). Most projects in the space are the protocol + SDKs, a starter template, or a payment facilitator. Agent402 is the applied layer — a ready-to-run x402 server that already speaks the protocol and ships 500+ working tools, so you don't have to build the catalog yourself.

• Want the protocol or an SDK? → coinbase/x402.
• Want a server you can run today that actually does things over x402 + MCP? → you're here.
• Self-hostable, deterministic, free via proof-of-work without a wallet, and non-custodial on the payment tools (your agent signs with its own key — Agent402 never holds funds).

Listed in the official MCP Registry and discoverable in the Coinbase x402 Bazaar.

Works with AWS Bedrock AgentCore Payments out of the box — AgentCore orchestrates x402, which is the protocol Agent402 already speaks. Point the AgentCore Gateway at https://agent402.tools/mcp for all 500+ tools, or use agent402-strands for a curated subset inside a Strands agent. Five-minute recipe: wiki: AWS Bedrock AgentCore.

Tollbooth — pay-per-crawl for your site (the other side of x402)

Charge AI crawlers that hit your site. Humans browse free; known bots get 402 Payment Required and can pay in USDC over x402 — or solve a free proof-of-work. The open, crypto-native answer to Cloudflare's closed pay-per-crawl: no CDN lock-in, no Stripe, no merchant-of-record, no signup.

• Product page · pricing · live install: agent402.tools/tollbooth
• Managed Tollbooth Cloud (Solo / Team / Agency / Enterprise): agent402.tools/tollbooth/cloud — join the waitlist
• Run it yourself (MIT, npm): npm i agent402-tollbooth · tollbooth/ · tollbooth/README.md

Runs as Express middleware, a Next.js / Vercel Edge middleware, a Cloudflare Worker, a reverse proxy, or a WordPress plugin (beta). Drop-in templates in tollbooth/deploy/. One Web-Crypto core powers all of them.

Repository map

Path	What
src/server.js	Express app + the tool catalog (routes, prices, schemas, discovery)
src/tools/	The tool kits (web, PDF, media, images, live data, crypto/x402, 216 pure-CPU utilities) — add tools here
src/mcp-http.js	Hosted MCP connector (streamable HTTP, authless free tier)
src/pow.js	Proof-of-work tier (signed, single-use, slug-scoped challenges)
src/payments.js	Optional x402 v2 wiring: USDC on Base/Solana/Polygon/Arbitrum/Monad/Stellar/Algorand + USDG on Robinhood Chain (8 chains), CDP facilitator, Bazaar discovery
src/x402-index.js	x402 Index + Smart Order Router: cross-seller crawl, auto-discovery, health-aware routing, per-chain marketplace pages (/stellar, /algorand)
src/sell.js	/sell — the seller front door: free self-serve listing (POST /api/index/register) or agent402-tollbooth for pay-per-crawl
mcp/	The agent402-mcp npm package (stdio MCP server)
client/	The agent402-client buyer SDK (find() + call() with auto-payment)
tollbooth/	The agent402-tollbooth pay-per-crawl gate (Express / edge / proxy)
adapters/	Drop-in tools for OpenAI / Anthropic / AI SDK / LangChain / LlamaIndex
wiki/	Source for the GitHub wiki (CI-synced)
scripts/	Tests, demos, ops tooling

Contact

• Email: [email protected]
• X / Twitter: @Agent402Tools
• GitHub: MikeyPetrillo/Agent402

Contributing

PRs that add useful tools, fix bugs, or improve docs are very welcome — see CONTRIBUTING.md. MIT licensed. Maintained by Havok Holdings LLC.