# x402-tools

Pay-per-call utility APIs for AI agents. Paid in USDC on Solana mainnet via the [x402 protocol](https://x402.org) — no accounts, no API keys.

## Endpoints

| Path                        | Price (USD) | Returns                | Purpose |
|-----------------------------|------------:|------------------------|---------|
| `POST /render`              | $0.005  | `application/pdf`      | Raw HTML → PDF |
| `POST /render-url`          | $0.005  | `application/pdf`      | Public URL → PDF |
| `POST /url-to-markdown`     | $0.002  | JSON                   | Public URL → clean Markdown (Readability + Turndown) |
| `POST /regex-from-examples` | $0.005  | JSON                   | Examples → regex pattern (validated) |
| `POST /text-to-cron`        | $0.001  | JSON                   | "every Tuesday at 3pm" → cron + next 5 fires |
| `POST /timezone-math`       | $0.001 | JSON                   | NL or datetime → timezone-converted result |
| `POST /holiday-check`       | $0.001 | JSON                   | Date + country → public holiday lookup |
| `POST /fake-data`           | $0.005  | JSON                   | Schema + count → locale-aware fake rows (Faker.js, ≤100/call) |
| `POST /airport-atis`        | $0.01   | JSON                   | ICAO code → live D-ATIS weather (temp, dewpoint, ATIS letter) with METAR fallback |
| `POST /color-palette`       | $0.001  | JSON                   | Base hex or seed string → deterministic palette (hex/rgb/hsl) across harmony modes |

All paid endpoints accept JSON and respond with either `application/pdf` (binary) or `application/json`.

## Free endpoints

- `GET /` — service descriptor (price + schemas + examples)
- `GET /health` — liveness + browser pool status
- `GET /llms.txt` — agent-discoverability blurb
- `GET /docs.md` — this document

## Payment

First unpaid POST returns HTTP `402` with the payment requirements base64-encoded in the `payment-required` response header. Sign the appropriate USDC transfer with your Solana keypair and retry with the `PAYMENT-SIGNATURE` header. We use [PayAI](https://facilitator.payai.network) as the facilitator — they cover SOL gas, so the payer only needs USDC.

## Security model

- Render endpoints (`/render`, `/render-url`, `/url-to-markdown`) do not sanitize HTML and run it in a sandboxed Chromium tab. No persistence.
- URL endpoints reject any host that resolves to a private/loopback IP (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16, IPv6 loopback/ULA/link-local).
- Body size caps: HTML ≤ 2 MB. Text/list inputs ≤ 500 chars / 50 items.
- LLM-backed endpoints (`/regex-from-examples`, `/text-to-cron`) call an OpenRouter model under the hood; output is validated server-side before returning.