# Keryx

> The paid tool registry for AI agents at https://keryxhq.xyz
> Discover tools, pay per call in USDC on Arc (eip155:5042002) via x402. No API keys. No accounts.

## Free endpoints (no payment required)

- [https://keryxhq.xyz/api/tools](https://keryxhq.xyz/api/tools) — full registry (id, price, args schema, sampleArgs)
- [https://keryxhq.xyz/api/demo](https://keryxhq.xyz/api/demo)?toolId=crypto.price — free sample before pay (live upstream, no USDC)
- [https://keryxhq.xyz/api/receipt/verify](https://keryxhq.xyz/api/receipt/verify) — POST {id|txHash} to prove a settlement (R0–R5; R5 = Arc RPC receipt)
- [https://keryxhq.xyz/.well-known/x402](https://keryxhq.xyz/.well-known/x402) — machine-readable x402 discovery manifest
- [https://keryxhq.xyz/llms.txt](https://keryxhq.xyz/llms.txt) — this file
- [https://keryxhq.xyz/keryx-openapi.json](https://keryxhq.xyz/keryx-openapi.json) — OpenAPI 3.1
- [https://keryxhq.xyz/quickstart.ts](https://keryxhq.xyz/quickstart.ts) — copy-paste TypeScript buyer agent
- [https://keryxhq.xyz/quickstart.py](https://keryxhq.xyz/quickstart.py) — copy-paste Python buyer agent
- [https://keryxhq.xyz/api/mcp](https://keryxhq.xyz/api/mcp) — MCP JSON-RPC (Claude Code, Cursor, Copilot) — subsidized today
- [https://keryxhq.xyz/docs](https://keryxhq.xyz/docs) — human + agent integration docs
- [https://keryxhq.xyz/ask](https://keryxhq.xyz/ask) — cost-aware agent playground (Keryx-sponsored settlement)
- [https://keryxhq.xyz/try](https://keryxhq.xyz/try) — minute-by-minute testing guide
- [https://keryxhq.xyz/registry](https://keryxhq.xyz/registry) — browse tools in the UI
- [https://keryxhq.xyz/live](https://keryxhq.xyz/live) — public settlement ledger
- [https://keryxhq.xyz/for-judges](https://keryxhq.xyz/for-judges) — Lepton judge one-pager
- [https://keryxhq.xyz/publish](https://keryxhq.xyz/publish) — list a tool (Arc wallet)

## Paid endpoint (x402 / USDC on Arc)

All paid execution goes through **POST https://keryxhq.xyz/api/call**.
Body: `{ "toolId": "<id>", "args": { ... } }`.
First call without `X-PAYMENT` → HTTP 402 with `accepts[]` and root-level `extensions.bazaar` (input/output).
Retry with signed `X-PAYMENT` → HTTP 200 + result + settlement.

Network: `eip155:5042002` · Asset: USDC (`0x3600000000000000000000000000000000000000`) · Pay to: tool publisher wallet (see 402 `payTo`) · Active: Arc Testnet

## Catalog

- `solana.token-activity` — $0.005: Live trading data for a Solana token: top DEX pairs, 24h volume, buy/sell counts, liquidity, and market cap.
- `solana.launches` — $0.003: Freshly-boosted Solana token profiles from DexScreener with descriptions, links, and dex URLs.
- `solana.rug-check` — $0.002: Live risk assessment from rugcheck.xyz: numeric score, normalised score, LP lock percentage, and every flagged risk.
- `search.web` — $0.004: Factual search over Wikipedia. Returns page titles, short extracts, and URLs. Best for definitions, history, geography, notable facts, and established knowledge. NOT for prices, availability, bookings, current events, commercial recommendations, or live data.
- `crypto.trending` — $0.001: The most-searched coins on CoinGecko right now, with price, 24h change, market cap, and rank.
- `weather.current` — $0.002: Live current weather for any lat/lon. Worth paying for when the user needs up-to-the-minute conditions (travel today, outdoor plans, severe weather). Not needed for general city descriptions.
- `weather.forecast` — $0.003: Hourly + daily forecast for a location (up to 7 days). Worth it for concrete near-term travel or event planning. Not needed for generic 'Berlin has seasons' advice.
- `finance.exchange-rates` — $0.002: Live fiat + crypto exchange rates for any base currency (200+ currencies). Call when you need current rates for a specific conversion or comparison you will show the user.
- `finance.convert` — $0.002: Convert an amount from one currency to another using live rates. Only call when you are actually going to perform and display a specific conversion for the user.
- `geo.ip-lookup` — $0.002: Location, ISP, ASN, timezone and security flags for an IP (or caller's IP). Only useful when the user's actual location or network context materially affects the answer (e.g. local currency, nearby services, compliance).
- `dns.domain-whois` — $0.003: Registrar, creation/expiry dates, name servers and status for a domain name.
- `web.hacker-news` — $0.001: Top stories from Hacker News: title, url, score, comments, time.
- `web.github-repo` — $0.002: Public repo metadata: stars, forks, description, language, license, last push.
- `crypto.price` — $0.002: Real-time price, market cap, 24h change for one or more coins (CoinGecko).
- `utility.qr` — $0.001: Generate a QR code image URL for any text (URL, text, wallet address, etc.).
- `demo.content-block` — $0.004: Example of a paid creator tool. Returns a monetized knowledge snippet. Onchain payTo is the external creator's Arc wallet (0x3AfD…B34E), not the Keryx treasury — click the tx hash on /live to verify.
- `geo.country` — $0.001: Basic country data: capital, population, currencies, languages, region. Mostly useful for structured lookup when building a specific comparison or form. General knowledge about Germany is usually sufficient.
- `time.current` — $0.0005: Precise current time in unix seconds, ISO, and human formats. Call when the agent must not hallucinate the date or needs a fresh timestamp for logs, expiries, or time-based decisions.
- `utility.uuid` — $0.0005: Generate a random UUID v4. Useful when an agent needs a unique identifier for plans, sessions, or objects it is creating.
- `crypto.btc-dominance` — $0.0015: Live BTC and ETH dominance percentages plus total crypto market cap from CoinGecko. Worth calling when the agent needs a broad market regime signal before making allocation or timing decisions.

## Quick unpaid probe

```bash
curl -i -X POST https://keryxhq.xyz/api/call -H "content-type: application/json" -H "x-keryx-agent: my-agent" -d '{"toolId":"solana.token-activity","args":{"mintOrSymbol":"BONK"}}'
# → HTTP 402 with accepts[0] (scheme exact, network eip155:5042002, USDC amount)
```

## How to pay

1. `GET /api/demo?toolId=…` — free sample of the response shape.
2. `GET /api/tools` — pick a toolId and args.
3. `POST /api/call` without payment → read `accepts[0]` and root `extensions.bazaar`.
4. Sign EIP-3009 `transferWithAuthorization` for that amount/asset/payTo/network.
5. Retry `POST /api/call` with header `X-PAYMENT: <base64 payload>`.
6. Read result + settlement; prove with `POST /api/receipt/verify`; audit on `/live`.

## Buyer quickstarts

- TypeScript: https://keryxhq.xyz/quickstart.ts
- Python: https://keryxhq.xyz/quickstart.py

## MCP + /ask (subsidized today)

```json
{
  "mcpServers": {
    "keryx": {
      "type": "http",
      "url": "https://keryxhq.xyz/api/mcp"
    }
  }
}
```

MCP and `/ask` are currently Keryx-sponsored (clients lack wallet headers).
Ledger entries still record real Arc txs when the local facilitator is active.
Autonomous buyer agents that pay themselves must use `/api/call` + a wallet (see quickstarts).

## Economics note

Onchain `transferWithAuthorization` pays 100% of the call price to `payTo` (publisher).
The 5% platform fee is ledger accounting today; a separate treasury split transfer is roadmap.

## Publish

Human form: https://keryxhq.xyz/publish
API: POST https://keryxhq.xyz/api/publishers/tools (EIP-191 signed ownership).