# agents.md — x402 Search API

Instructions for AI agents calling https://x402.eleeth.com.

## What this is

Pay-per-call APIs for AI agents: web search, page reading, AI chat, AI image generation, AI video generation, crypto prices, weather, stock quotes, currency conversion, news headlines, DNS lookup, archived page snapshots, RSS feeds as JSON, article summaries, domain WHOIS, certificate-transparency subdomain discovery, SEO audits, GitHub repo stats, arXiv paper search, Wikipedia summaries, SEC company financials, crypto fear/greed index, public holidays, website screenshots, JS-rendered page reading, image OCR, file metadata reports, and PDF text extraction. $0.01 USDC per call ($0.02 chat/summarize/seo/render/ocr/metadata/pdftext, $0.05 images/screenshots, $0.25 text-to-speech, $0.50 videos/podcasts), paid in USDC on Base mainnet via the x402 payment protocol ("exact" scheme, x402 v2). No account, no API key, no signup exists or is needed — the payment is the credential.

## Endpoints

- `POST /api/search` — JSON body `{"query": "...", "num_results": 5}`. $0.01.
- `GET /api/search?q=...&num=5` — same results, for simple clients. $0.01.
- `POST /api/read` — JSON body `{"url": "https://..."}`. Returns the page's clean text. $0.01.
- `GET /api/read?url=https://...` — same, for simple clients. $0.01.
- `POST /api/chat` — JSON body `{"message": "..."}`. AI chat. $0.02.
- `GET /api/chat?q=...` — same, for simple clients. $0.02.
- `POST /api/image` — JSON body `{"prompt": "..."}`. Returns image bytes. $0.05.
- `GET /api/image?prompt=...` — same, for simple clients. $0.05.
- `GET /api/crypto?coin=bitcoin` — live USD price + 24h change. $0.01.
- `GET /api/weather?city=Austin` — current conditions + today's forecast. $0.01.
- `GET /api/stock?ticker=AAPL` — stock quote. $0.01.
- `GET /api/fx?from=USD&to=MXN` — currency conversion (omit to= for full table). $0.01.
- `GET /api/news?q=bitcoin` — latest headlines. $0.01.
- `GET /api/dns?domain=example.com&type=A` — DNS records. $0.01.
- `GET /api/wayback?url=https://...` — closest archived snapshot. $0.01.
- `GET /api/rss?url=https://.../feed.xml` — any RSS/Atom feed as JSON. $0.01.
- `GET /api/summarize?url=https://...` — AI summary of any article. $0.02.
- `GET /api/whois?domain=example.com` — domain WHOIS via RDAP. $0.01.
- `GET /api/certs?domain=example.com` — subdomains from certificate transparency logs. $0.01.
- `GET /api/seo?url=https://...` — instant SEO audit with score. $0.02.
- `GET /api/github?repo=owner/name` — repo stats. $0.01.
- `GET /api/arxiv?q=...&n=5` — research paper search. $0.01.
- `GET /api/wiki?topic=Bitcoin` — Wikipedia summary. $0.01.
- `GET /api/sec?ticker=AAPL` — SEC company financial facts. $0.01.
- `GET /api/feargreed` — crypto Fear & Greed index. $0.01.
- `GET /api/holidays?country=US&year=2026` — public holidays. $0.01.
- `POST /api/video` — JSON body `{"prompt": "..."}`. $0.50. Returns a job ticket — the ~10s 720p clip renders in minutes.
- `GET /api/video?prompt=...` — same, for simple clients. $0.50.
- `GET /api/video/status?id=...` — free. Poll until `status` is `done`, then fetch `video_url`.
- `POST /api/tts` — JSON body `{"text": "...", "voice": "..."}`. $0.25. Returns a job ticket — spoken-word mp3 renders in minutes. Poll `GET /api/media/status?id=...` (free), download from `media_url`.
- `POST /api/podcast` — JSON body `{"topic": "..."}` or `{"script": "..."}`. $0.50. Returns a job ticket — full episode mp3 renders in minutes. Poll `GET /api/media/status?id=...` (free).
- `POST /api/translate` — JSON body `{"text": "...", "target": "Spanish"}`. $0.01.
- `POST /api/sentiment` — JSON body `{"text": "..."}`. $0.01. Returns positive, negative, or neutral.
- `GET /api/places?query=coffee&lat=..&lon=..` — find restaurants, shops, landmarks. $0.01.
- `GET /api/qrcode?text=https://...&size=256` — QR code as PNG bytes. $0.01.
- `POST /api/screenshot` — JSON body `{"url": "https://..."}`. $0.05. Returns a job ticket — a full-page PNG renders on dedicated hardware in about a minute. Poll `GET /api/box/status?id=...` (free), download from `file_url`.
- `GET /api/screenshot?url=https://...` — same, for simple clients. $0.05.
- `POST /api/render` — JSON body `{"url": "https://..."}`. $0.02. Returns a job ticket — the page renders in a real browser (JavaScript included) and returns clean text in about a minute. Poll `GET /api/box/status?id=...` (free).
- `GET /api/render?url=https://...` — same, for simple clients. $0.02.
- `POST /api/ocr` — JSON body `{"file": "<base64>", "filename": "photo.png"}` or `{"url": "https://..."}`. $0.02. Returns a job ticket — image text extracted in about a minute. Poll `GET /api/box/status?id=...` (free).
- `POST /api/metadata` — JSON body `{"file": "<base64>"}` or `{"url": "https://..."}`. $0.02. Returns a job ticket — full EXIF/metadata report as JSON in about a minute. Poll `GET /api/box/status?id=...` (free).
- `POST /api/pdftext` — JSON body `{"file": "<base64>"}` or `{"url": "https://..."}`. $0.02. Returns a job ticket — clean PDF text in about a minute. Poll `GET /api/box/status?id=...` (free).
- `GET /health` — free. Returns `{"ok":true}`.

## How to pay (x402 v2)

1. Call the endpoint with no payment header.
2. You receive HTTP 402. Read the `PAYMENT-REQUIRED` response header (base64 JSON): it gives the amount (10000 = $0.01 USDC, 6 decimals), the USDC contract, the network, and the payTo wallet.
3. Sign the USDC transfer per those instructions and retry the request with the `X-PAYMENT` header.
4. The payment is verified on-chain, the search runs, and results return as JSON: `{"provider","query","results":[{"title","url","snippet"}]}`.

Any x402 v2 client library (@x402/core / x402-fetch) performs these steps automatically.

## Machine-readable discovery

- `/.well-known/x402` — resource catalog
- `/openapi.json` — full API spec with per-operation pricing metadata

## Contact

seo@eleeth.com