Agent402
MikeyPetrillo/Agent402
The open-source, self-hostable x402 + MCP server: 1,100+ tools for AI agents, plus agent402-tollbooth for charging AI crawlers. Run free, or charge per call in USDC on Base.
Instalação
npx convez-ai MikeyPetrillo/Agent4021 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Agent402 — the open-source, self-hostable x402 + MCP server (1,100+ tools for AI agents)
What makes it different: most x402 services are closed gateways exposing a handful of tools. Agent402 is the open-source, self-hostable one — the whole ~1,100-tool catalog, runnable yourself — and it's two-sided: it also ships
agent402-tollbooth, an open pay-per-crawl gate for the other side of x402.
Framework adapters (drop-in tools for the major agent stacks — auto-payment underneath):
Give your AI agent ~1,100 ready-to-use web tools from one server — browser rendering, web search, PDFs, images, live data, crypto/payments helpers, and ~1,040 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) — 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 ~1,100 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"}'
What's in the catalog (~1,100 tools)
| Examples | |
|---|---|
| Browser & web | render (headless Chromium, executes JS), screenshot, extract (article→markdown), meta |
| Live search | search — a real web index behind one call |
| 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) |
| Live data | fx-rate (ECB), barcode-lookup (Open Food Facts), gov-data (data.gov), weather-forecast/weather-alerts, earthquakes (USGS) |
| 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 |
| ~1,040 pure-CPU utilities | hashing, JWT, base58, JSON⇄CSV/YAML, token-count, text-chunk, json-validate, text stats, cron math, validators, ~970 unit conversions |
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=<task> 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.
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[] |
// 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/.
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 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 ~1,100 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 ~1,100
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.
Sibling: agent402-tollbooth (open-source pay-per-crawl)
Want the other side of x402 — charging AI bots that crawl your site?
tollbooth/ is a self-hostable pay-per-crawl gate: drop it in
front of any site/API and humans browse free while AI crawlers pay per request
(USDC via x402, or free via proof-of-work). The open, crypto-native answer to
Cloudflare's closed pay-per-crawl — no CDN, no Stripe, no signup. Runs as
Express middleware, a reverse proxy, or on the edge (Cloudflare Workers /
Next.js middleware, via one Web-Crypto core). See tollbooth/README.md.
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, ~1,040 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, CDP facilitator, Bazaar discovery |
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 |
Contributing
PRs that add useful tools, fix bugs, or improve docs are very welcome — see CONTRIBUTING.md. MIT licensed. Maintained by Mikey Petrillo.