# x402 Agent Tools

<!-- mcp-name: io.github.signal-forge-ai/x402-agent-tools -->

Pay-per-call tools for AI agents. Pay with **USDC on Base** using the [x402](https://x402.org) protocol (HTTP 402). No API key, no signup, no account.

- Live: https://x402-agent-tools.x402agenttools.workers.dev
- For LLMs: [https://x402-agent-tools.x402agenttools.workers.dev/llms.txt](https://x402-agent-tools.x402agenttools.workers.dev/llms.txt)
- Discovery: [/.well-known/x402](https://x402-agent-tools.x402agenttools.workers.dev/.well-known/x402) · [/openapi.json](https://x402-agent-tools.x402agenttools.workers.dev/openapi.json) · [/health](https://x402-agent-tools.x402agenttools.workers.dev/health)
- MCP (remote, Streamable HTTP): `https://x402-agent-tools.x402agenttools.workers.dev/mcp`

## Tools and prices

| Endpoint | Price (USDC) | What it does |
|---|---|---|
| `GET /v1/markdown?url=` | $0.01 | Web page to clean Markdown |
| `GET /v1/extract?url=` | $0.04 | Structured JSON: meta/OpenGraph, JSON-LD, headings, links, tables, emails |
| `GET /v1/crawl?url=&max_pages=` | $0.16 | Same-origin crawl, up to 10 pages, Markdown each |
| `GET /v1/token-risk?address=` | $0.04 | Base token/contract heuristic risk check (proxy, owner, risky selectors) |
| `GET /v1/token-price?address=` | $0.005 | Base token USD price (GeckoTerminal, DefiLlama fallback) |
| `GET /v1/wallet-profile?address=` | $0.02 | Base wallet ETH/USDC balances, nonce, recent USDC transfers |
| `GET /v1/fx?from=&to=&amount=&date=` | $0.002 | Fiat FX rates (ECB reference) |
| `GET /v1/alerts/latest?limit=` | $0.01 | Latest factual crypto/market alerts |
| `GET\|POST /v1/alerts/pass` | $1 | 7-day Bearer token for `GET /v1/alerts?since=` |
| `GET /v1/alerts/sample` | free | 3 alerts delayed 60+ min |

Crypto alerts are visible about 1 to 2 minutes after they fire. Stock news alerts are delayed 15 to 20 minutes. Alerts are factual observations (price/volume moves) only: no scores, no buy/sell calls, not investment advice.

## Free trial

The first **3 calls per day per caller** (hashed IP) to `/v1/markdown`, `/v1/token-price` and `/v1/fx` are free; just call without a payment header. A global daily cap applies. The `X-Free-Trial-Remaining` response header shows what is left. Crawl and alert passes are never free.

## How agents pay (x402)

1. Call an endpoint. You get `402 Payment Required` with a `PAYMENT-REQUIRED` header (x402 v2) and a JSON body listing `accepts` (scheme `exact`, network `eip155:8453`, asset USDC, `payTo`, amount).
2. Sign the USDC authorization with your wallet and retry with the `PAYMENT-SIGNATURE` (v2) or `X-PAYMENT` (v1) header.
3. The facilitator verifies and settles; you get the result plus a `PAYMENT-RESPONSE` header.

```js
// any x402 client works, e.g. @x402/fetch:
import { wrapFetchWithPayment } from "@x402/fetch";
const fetchWithPay = wrapFetchWithPayment(fetch, yourX402Client);
const res = await fetchWithPay("https://x402-agent-tools.x402agenttools.workers.dev/v1/markdown?url=https://example.com");
```

## MCP

Remote MCP server, stateless Streamable HTTP (JSON responses), no install needed:

```json
{ "mcpServers": { "x402-agent-tools": { "type": "http", "url": "https://x402-agent-tools.x402agenttools.workers.dev/mcp" } } }
```

Tools: `web_markdown`, `web_extract`, `web_crawl`, `base_token_risk`, `base_token_price`, `base_wallet_profile`, `fx_rates`, `alerts_latest`, `alerts_sample` (free).

Paid tools called without payment return `isError: true` with the x402 requirements in `structuredContent["x402/payment-required"]`. Retry the same `tools/call` with the base64 x402 payment payload in the `PAYMENT-SIGNATURE` HTTP header, or in `params._meta["x402/payment"]`. Settlement info comes back in `result._meta["x402/payment-response"]`.

No npm needed: any MCP client with HTTP transport works, or plain curl:

```sh
curl -s https://x402-agent-tools.x402agenttools.workers.dev/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Self-host

Cloudflare Worker (Hono + `@x402/hono`).

```sh
npm install
# edit wrangler.toml: account_id, KV namespace id, PAY_TO (your own receive address)
npx wrangler secret put ALERTS_HMAC   # random secret for alert tokens
npx wrangler deploy
```

No secrets live in this repo; everything sensitive is a Wrangler secret or env var.

## License

MIT. Operated by an autonomous AI agent team. Informational data only, not investment advice.