keryx

# Keryx 🏛️

[![npm: keryx-mcp](https://img.shields.io/npm/v/keryx-mcp?logo=npm&label=keryx-mcp&color=CB3837)](https://www.npmjs.com/package/keryx-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.tang--vu%2Fkeryx-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=keryx)
[![live: keryx.cc](https://img.shields.io/badge/live-keryx.cc-1aa251)](https://keryx.cc)
[![settles on Arc testnet](https://img.shields.io/badge/settles_on-Arc_testnet-1f1f1f)](https://docs.arc.network)
[![payments: Circle x402](https://img.shields.io/badge/payments-Circle_x402-2775CA)](https://github.com/circlefin/arc-nanopayments)

**Every time an AI uses a creator's work as a source, the creator gets paid — instantly.**

🔗 Live: **[keryx.cc](https://keryx.cc)** — free to try, no wallet, no sign-up
 ·  ▶️ `npm run demo` — the whole loop, real settlement, ~90s
 ·  🤖 `npx -y keryx-mcp@latest` — plug Keryx into any MCP agent
 ·  🧩 [Fork the Arc primitives](https://github.com/tang-vu/keryx-arc-primitives)

---

## The problem

The web's economics assume a human reader: you write, people visit, attention becomes ads,
subscriptions, tips. AI agents broke that contract. They read everything and send back nothing —
no click, no view, no cent. Every answer an assistant gives is built on someone's work, and that
someone is invisible at the exact moment their work proves its value.

Keryx (κῆρυξ — *herald*) exists to fix that one moment. It makes **citation itself the payment
event**: the instant an agent relies on your writing to answer a question, you are paid,
proportional to how much you helped, settled sub-cent in USDC on [Arc](https://docs.arc.network).
No accounts, no invoices, no ad tech. A creator onboards by pasting an RSS URL. An agent pays
because paying is cheaper than not knowing.

## What Keryx is

Keryx is a **citation-toll reading agent** — an autonomous reader with a wallet, and the payment
rail underneath it. Give it a question and a budget:

1. It **decomposes** the question into sub-claims and **discovers** candidate sources (free previews).
2. It **decides**, per source: *buy / skip / cache* — expected value vs price vs remaining budget,
   with a human-readable rationale for every choice.
3. It **pays the x402 toll** only for what it buys, checks **sufficiency** after each read, and
   stops early when it has enough.
4. It **synthesizes** a grounded answer with inline citations, **weighs each source's real
   contribution**, and **settles a weighted USDC nanopayment to every creator it cited** —
   multi-author works split on-chain, 100% to creator wallets, 0% platform fee.

The result is a working micro-economy: readers that pay by default, and writers that earn by
being *useful* — not by being clicked.

## An agent that genuinely decides

Most "payment agents" are scripts with a wallet. Keryx's differentiator is **visible agency** —
the model reasons about money and shows its work, streamed live to the UI:

- **Buy / skip / cache with rationale** — every spend decision is logged in plain language, per source.
- **Adjudication** ⚖️ — when two sources conflict, the agent doesn't average them; it decides which
  to trust and says why.
- **Confidence verdict** 📊 — it rates its own answer (High / Moderate / Low) and hedges the prose
  accordingly, instead of bluffing.
- **Cross-query memory** — sources that proved useful (or useless) in past runs *on the same
  subject* shift future buy/skip decisions. A source is scored against the runs that actually read
  it, so a skip never becomes evidence against the source it skipped.
- **Semantic discovery** — candidate matching by embedding similarity, not keyword luck.
- **Emergent frugality** — it stops early, reuses its cache, and correctly spends *nothing* when
  nothing is worth buying.

Money safety is enforced in code, not by the model: the LLM proposes value; the orchestrator
enforces the hard budget cap, so a hallucinated number can never overspend. An economic-invariant
test suite (spend ≤ budget, payouts = weights, splits sum exactly) runs in CI on every push.

Example trace (real output):

```
[decide]  BUY Agent Economy Weekly — strong match on x402, autonomous, commerce; worth the $0.004 toll
[decide]  SKIP Garden & Soil Monthly — weak match (no key terms); not worth $0.002
[fetch]   Paid $0.004 to Agent Economy Weekly — S1
[sufficiency] Read 2 sources covering all sub-claims; stopping early to save budget
[settle]  Settled $0.015 → Mara Okoye · $0.010 → Devin Park   (60/40 author split)
📊 $0.032 spent → 100% to creators · 3 bought / 3 skipped
```

## For creators

- **Onboard from your own wallet** — paste an RSS feed at [keryx.cc/register](https://keryx.cc/register)
  and your wallet writes the source to the on-chain registry itself. Keryx sets up the x402-priced
  endpoint and the free preview; it never holds your key, and the faucet on that page covers the gas.
  **All 20 listed sources are written to the on-chain registry**, including real public feeds —
  Hugging Face, Vitalik Buterin, CoinDesk, the Ethereum Foundation, Stripe, Latent Space,
  Simon Willison — each earning per citation.
- **Own your payout** — the payout address is the wallet you signed in with. The first owner-verified
  creator ([conzit.com](https://conzit.com)) proved feed ownership, set its address, was cited &
  paid end-to-end — and has since claimed its registry record from its own wallet, so its on-chain
  `creator` is the creator, not Keryx. We've also proposed this as an opt-in convention upstream in
  [RSSHub](https://github.com/DIYgod/RSSHub/discussions/22315).
  *Honest note:* the demo sources seeded before this switch still have operator-held payout keys —
  they are Keryx's own sample publications, not third-party creators. Nine of the twenty on-chain
  records also name Keryx's treasury as their registry `creator`, so the treasury, not the source
  wallet, can update or deactivate those nine. The payout address is correct on all twenty — an
  hourly watchdog re-reads every record from the chain and publishes the comparison on
  [`/status`](https://keryx.cc/status).
- **Know the moment you're cited** — opt into a plain **email alert** (no webhook server needed,
  rate-capped, one-click unsubscribe) and/or signed webhooks that fire the instant a citation
  settles; every payout on your public earnings page shows the actual *question* your work helped
  answer.
- **Show it off** — an embeddable **"Cited by Keryx" badge** (live SVG at `/api/creator/<id>/badge.svg`)
  displays your real citation count + USDC earned on your own site, with copy-paste Markdown/HTML on
  each creator page. Payouts become portable, verifiable proof.
- **Cash out yourself, gas-free** — a self-serve, non-custodial withdraw: your wallet signs a
  Gateway burn intent in the browser, the treasury relays gas. Real creators have executed real
  on-chain cash-outs.
- **Keep everything** — 100% of every citation reward goes to creator wallets. 0% platform fee.
- **Squat-proof identity** — sources live in an on-chain SourceRegistry
  ([`0x2e12Fa…`](https://testnet.arcscan.app/address/0x2e12Fa3256B21b9d8726933b5c4bfBDCc740e536))
  with creator-scoped IDs and on-chain multi-author splits.

## For developers & agents

- **Free, no-wallet trial** — [keryx.cc](https://keryx.cc) answers without any setup, with a
  graceful upgrade path when you outgrow the free budget.
- **Browser extension** ([`extension/`](extension/)) — highlight text on any page and ask Keryx
  from a toolbar popup, or right-click to list a page you own as a paid source. A thin,
  no-key client over the OpenAI-compatible endpoint; load unpacked on any Chromium browser.
- **Remote MCP** — connect an MCP client directly to [`https://keryx.cc/mcp`](https://keryx.cc/mcp)
  over Streamable HTTP: no package or local wallet process. The `research` tool has an anonymous,
  IP-limited trial; an ask-scoped `kx_live_…` Bearer key raises the cap and attributes usage to its
  verified wallet. Creator rewards still settle in USDC on Arc. Quick connect:
  `codex mcp add keryx --url "https://keryx.cc/mcp?client=codex"` or
  `claude mcp add --transport http keryx "https://keryx.cc/mcp?client=claude"`.
  The interactive setup guide is at [`/integrations/mcp`](https://keryx.cc/integrations/mcp).
- **Local x402 MCP** — on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=keryx);
  `npx -y keryx-mcp@latest` keeps the caller-funded path: its local Arc wallet pays Keryx's x402
  toll before Keryx researches and pays creators.
- **Discord slash command** — [install the Keryx app](https://discord.com/oauth2/authorize?client_id=1527619548809924678)
  in any server and type `/ask`: the reply embed carries the grounded answer, every creator paid,
  and a link to the dispatch trace. No bot process — signed interactions POST straight to the API
  ([`docs/discord-bot-setup.md`](./docs/discord-bot-setup.md)).
- **Telegram bot** — DM [@keryxai_bot](https://t.me/keryxai_bot) any question (or `/ask …` in a
  group): same full reasoning loop, same real creator payouts, answered in-chat with a
  dispatch-trace link. Webhook-only, no polling process
  ([`docs/telegram-bot-setup.md`](./docs/telegram-bot-setup.md)).
- **Slack slash command** — a `/keryx …` command for any workspace: signed requests POST straight
  to `/api/slack/commands`, the same full reasoning loop and real creator payouts answered in-channel
  with a dispatch-trace link. No bot token or scopes — replies ride the command's `response_url`.
  Setup + app manifest in ([`docs/slack-bot-setup.md`](./docs/slack-bot-setup.md)).
- **Agent-to-agent API** — `POST /api/agent/ask` lets other agents buy Keryx's research over x402:
  an agent paying an agent that pays creators, end to end.
- **OpenAI-compatible endpoint** — point any OpenAI SDK or tool (LangChain, LlamaIndex, OpenWebUI,
  LibreChat, Continue) at `https://keryx.cc/a