keryx
by tang-vu
README.md
# Keryx ποΈ
[](https://www.npmjs.com/package/keryx-mcp)
[](https://registry.modelcontextprotocol.io/v0/servers?search=keryx)
[](https://keryx.cc)
[](https://docs.arc.io)
[](https://github.com/circlefin/arc-nanopayments)
[](https://github.com/tang-vu/keryx/actions/workflows/ci.yml)
Keryx is a research agent for researchers and builders. Give it a question and a
budget: inspect its source choices, reuse the cited evidence, and see USDC payment
receipts for eligible creators whose work it cites. Production runs on Arc mainnet
with Circle Gateway and x402.
**[Try Keryx](https://keryx.cc)** Β· **[Windows downloads](https://keryx.cc/download)** Β·
**[MCP / API / CLI](https://keryx.cc/integrations)** Β·
**[Watch the product demo β 2:49, narrated and subtitled](https://youtu.be/4uHylKXcv5Y)**
Developed continuously since June 2026: source discovery and creator payments now connect
to research briefs, literature tools and durable desktop/CLI tasks. Developers and
researchers use it for concrete work; [recorded tasks](#see-users-use-it) include
app development, scholarship research and a returning builder's audio-preview review.
**Reviewing the Tameion continuation?** Start with the [reviewer guide](docs/reviewer-start.md)
for the event delta, current usage and direct evidence. The
[submission pack](docs/tameion-submission.md) keeps reporting periods and historical checkpoints.
## What you can do
| Workflow | What Keryx provides | Guide |
| --- | --- | --- |
| Research original sources | Public-web and scholarly discovery, exact Crossref DOIs/arXiv versions, bounded HTML/PDF reads and cited reports | [Scholarly research](docs/scholarly-research.md) |
| Turn reading into writing | Paper screening, notes, editable comparisons, retained-excerpt related-work drafts and cited-sentence checks; Markdown/LaTeX and reference/evidence exports | [Literature workspace](docs/literature-workspace.md), [evidence drafts](docs/evidence-drafts.md) |
| Keep a task across sessions | Windows Tauri app and task CLI share private workspaces, pinned seller/network/caps, original-job recovery, offline results and native exports | [Desktop](docs/desktop-alpha.md), [task CLI](docs/operator-task-alpha.md) |
| Inspect economic decisions | BUY/SKIP/CACHE reasons under USDC and attention limits; Decision Lab separates model proposals, selected plans, rules and observed actions | [Decision inspection](docs/tameion-submission.md#event-period-product-delta) |
| Pay and recover research | Separate access tolls and evidence-gated citation rewards; prepaid Operator checks obligations, capacity and liquidity before claiming a job | [Business Operator](docs/operator-business.md) |
| Plan repeat research | Research Monthly groups four manual Deep requests over 30 days, with explicit creator caps and renewal | [Monthly terms](docs/research-monthly.md) |
| Connect another tool | Web, API/OpenAI-compatible calls, remote and caller-funded stdio MCP, browser extension and Discord/Telegram/Slack adapters | [Integration roles](docs/surface-parity.md) |
The desktop prepares tasks and hands spending to the buyer explicitly. Metadata,
read excerpts and author judgments keep their own labels. See the
[release/source boundary](docs/tameion-submission.md#observed-delivery-and-supported-surfaces)
for published clients and newer merged features awaiting deployment.
## See users use it
**[HoΓ ng's Face Marker workflow β MCP inside Devin CLI, 1:53](https://github.com/tang-vu/keryx/releases/download/v0.27.63/hoang-keryx-mcp-user-workflow-20261002.mp4)**
shows an independent freelance developer researching app-policy and MediaPipe
questions while working on his codebase. This October 2 recording has English
chapter labels and original audio; its partial results, connection error and
sponsored Arc-testnet payment remain visible. The archived video restores access
after the original X account was suspended.
**[0xacee's software-design workflow β English video, 3:05](https://github.com/tang-vu/keryx/releases/download/v0.27.63/0xacee-keryx-user-workflow-20261012.mp4)**
shows research for storage and backups in a news-monitoring application. The owner
confirmed that 0xacee directly operated or supervised the session. The recording
retains a useful SQLite WAL result alongside partial and unsupported results;
English narration and captions explain the steps.
**[TrαΊ§n Minh HiαΊΏu's working paper β 65 reports, 202 research targets](https://github.com/tang-vu/keryx/releases/download/v0.27.63/hieu-keryx-research-pilot-20261013.pdf)**
shows a concrete academic output from another documented user. HiαΊΏu conducted
the research himself using sponsored Keryx Deep requests, with AI-assisted
analysis and writing. The paper examines payment signals and recorded evidence
coverage, with methods, tables, figures and a
[reproducibility package](https://github.com/tang-vu/keryx/releases/download/v0.27.63/hieu-keryx-research-pilot-20261013.zip).
See the [research story](docs/tameion-submission.md#research-artifact-trαΊ§n-minh-hiαΊΏu)
for attribution and the study's scope.
HoΓ ng, a freelance developer, used Keryx MCP inside Devin CLI for his Face Marker
app. Academic research and SaaS discovery are also documented in the
[outside-user stories](docs/tameion-submission.md#named-external-user-hoΓ ng-freelance-developer).
These are four contactable participants with documented use stories, rather than
the total user count. HoΓ ng's source payment is matched to sponsored testnet
settlement; other stories retain their own evidence scope. On October 15,
**0xacee returned with a VoiceReady development task**: retained MDN passages
informed review of browser object-URL cleanup. See the
[2:23 return recording](https://github.com/tang-vu/keryx/releases/download/v0.27.63/0xacee-voiceready-keryx-return-20261015.mp4)
and [case study](docs/case-studies/voiceready-2026-10-15.md), including the unsuccessful
FFmpeg research and the separate assistant implementation checks.
## Try it in two minutes β no wallet
The path below does not submit a question, ask for a signature, or spend anything.
1. Open the [recorded walkthrough](https://keryx.cc/walkthrough). It follows one
stored owner QA job from October 8: the answer, its CACHE/SKIP reasons, and
the receipt. Run the three checks separately. The payout check reads retained
SourceRegistry V1, not the V3 address reported by current health.
2. The same example is the [stored report](https://keryx.cc/dispatch/b144ef47-c2f5-46ec-bdb7-e62bc1314913)
and its [receipt](https://keryx.cc/api/dispatch/b144ef47-c2f5-46ec-bdb7-e62bc1314913/receipt):
zero access USDC and a recorded 0.025 USDC mainnet citation reward to Keryx
Engineering. The [reviewer guide](docs/reviewer-start.md#verify-the-example)
keeps the digest, the partial-result boundary, and the October 16 readback.
3. To ask a new question, open [keryx.cc](https://keryx.cc), choose Quick, and
read the displayed payer and budget before submitting. Sponsored admission
can be paused or capped. Submitted questions become public reports. Then
inspect the source excerpts, **Decision log**, and **Portable research receipt**.
A citation alone does not establish settlement.
## Usage so far
**October 17, 2026 snapshot.** Product activity, contactable participants and
distribution measure different things:
| Measure | Snapshot | Window |
| --- | --- | --- |
| Mainnet service activity | **216 recorded questions, 16 recorded accounts; 174 guest questions included in the 216** | Current mainnet deployment, checked October 17; accounts and questions are not unique-human counts |
| Task evidence | Four contactable participants; a documented October 15 return task; a user-led working paper using 65 retained reports | Case studies below; reports and repeat tasks are included activity, not additional people |
| Arc mainnet settlements | 116 settled payment records; 2.170250 USDC gross recorded volume | September 27βOctober 17, including owner/QA; incoming and outgoing records, not customer revenue |
| MCP distribution | 2,711 npm download events; 3,619 lifetime events | September 27βOctober 16 and June 23βOctober 16 respectively; overlapping totals |
| Website reach | 580 visits, approximately 1,430 page views; Cloudflare Exclude bots enabled | September 27, 00:00βOctober 17, 22:50 GMT+7; visits are sessions |
| Repository distribution | 41,654 clones, 1,528 unique cloners, 781 views and 49 unique visitors; 4 stars, 1 fork | GitHub API readback October 17; traffic window October 3β16 |
| Extension / community | 12 extension installs, 0 uninstalls; 44 @keryxpays followers; 8 Product Hunt upvotes | Extension console September 17βOctober 15; X checked October 17; Product Hunt snapshot October 13 |
The retained email review also records **27 Keryx-related contacts/interactions
across three mailboxes**, including product discussion, collaboration and invitations;
some outreach offers marketing services. Four further inbound LinkedIn contacts
followed the Product Hunt launch. These are relationship signals, separate from usage.
The [current evidence summary](docs/tameion-submission.md#october-17-current-evidence)
explains network provenance, payment recipients, email counting and the separate
testnet archive of **23 paid creator wallets**. Mainnet creator payouts and Keryx
operating-fee allocations are distinct. Downloads/clones may include automation.
[Live Ledger](https://keryx.cc/dashboard) and [public metrics](https://keryx.cc/api/metrics)
show current activity; dated snapshots remain available for comparison.
## What happened during Tameion
Starting from the [September 25 baseline](https://github.com/tang-vu/keryx/tree/2291753cc4fff2135d546227d5aafda287cbed7d),
Keryx grew from the earlier citation-toll agent into a research workflow across
desktop, terminal and agent tools. The event added durable tasks and private
exports, original-source and scholarly research, literature/drafting tools,
prepaid Operator recovery, creator-signed registration and decision inspection.
Production moved to Arc mainnet on October 4.
Newer merged work adds economic replay, supplied-review/cost analysis, signed
missing-evidence procurement and owner-bound completed-read import into drafts.
The [event delta](docs/tameion-submission.md#event-period-product-delta) distinguishes
deployed and published entry points from source awaiting the next release batch.
Funded evidence-provider execution and independently accepted paid-business
fulfillment remain validation milestones.
Builders can reuse the separate **[MIT-licensed Arc primitives library](https://github.com/tang-vu/keryx-arc-primitives)**:
integer micro-USDC allocation, two-toll x402 flows, required durable journal
interfaces, registry helpers, budget reservations and withdrawal helpers. Its
testnet defaults and host duties are described in [the maintained extraction](docs/arc-primitives-maintenance.md).
---
## 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*) makes **citation itself a payment event**: qualifying
evidence from an eligible creator earns a bounded, weighted citation reward,
with sub-cent USDC settlement on [Arc](https://docs.arc.io).
Creators verify publishing control and authorize payout terms; qualifying source evidence
and settlement determine their rewards. An agent pays because useful information can
be worth buying.
## 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** exact article candidates from free previews and the signed offer book.
2. It **decides**, per article version: *buy / skip / cache* β expected value vs effective 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 returns a **summary cited sentence by sentence**: each sentence is written from one
verbatim source excerpt, checked against it, and shown beside it, with explicitly
labelled research targets/gaps. Uncited prose is withheld; the answer
retains a **Low/incomplete** boundary, and allocates bounded citation rewards only
to eligible accepted sources. Creator payouts are settled only when recorded
payment evidence confirms settlement; multi-author rewards follow their payout split.
Ordinary short-bullet requests can retain their requested count and supported
output language when every target, reviewed sentence and qualifying excerpt fits
the same grounded layout. Otherwise the answer keeps inspectable target sections
and explains the unmet format. See [candidate scope and acceptance](docs/engineering/research-deliverable-quality-2026-10-08.md).
Unsupported output-language requests use English scaffold labels without forcing
statement translation; [language-selection scope](docs/engineering/output-language-2026-10-09.md)
records the finite parser and remaining localization gates.
The goal is to make useful evidence payable and its contribution inspectable.
## How source decisions work
Keryx exposes the model's source proposals, the bounded selection policy and the
observed result, streamed to the UI:
- **Buy / skip / cache with rationale** β every spend decision names the exact article version and explains why.
- **Open article market** β [`/market`](https://keryx.cc/market) and `GET /api/offers` publish exact payable versions, registry list prices, x402 paths, and verifiable EIP-712 discounts signed by publishers.
- **Source comparisons**: recorded exact excerpts let readers inspect differing sources.
The current claim-grounding candidate does not certify an independent synthesized
conclusion about which source is correct.
- **Confidence boundary**: the answer is labelled Low/incomplete.
Qualified source excerpts provide recorded support; target coverage estimates do not
verify each assertion or establish complete useful synthesis.
- **Sentence-cited summaries**: each summary sentence is written from one qualified literal
source excerpt, scored against that excerpt by a separate model review, and rendered
beside the verbatim source text. Sentences without a qualifying excerpt or review are
removed, and the answer falls back to excerpts alone when none survives. The review is
a model judgment, not proof; cross-source conclusions are not written. Accepted excerpt
citations still support rewards, with original paid-fetch debits, article bindings and
settlement identities. Production now uses Arc mainnet; see the
[current deployment and evidence limits](docs/mainnet-status.md).
Deployment does not establish complete useful synthesis or independent acceptance.
- **Evidence ledger** β every rewarded citation carries a claim-indexed exact quote. The
orchestrator verifies that quote against content it actually read before the marker can receive
a citation reward; rejected markers are removed from the answer.
- **Living answer receipts** β archived conclusions never silently change. Keryx flags when an
exact paid SHA-256/IPFS article version has been superseded, exposes a metadata-only freshness API,
and itemizes the source/evidence/coverage/settled-payment delta after a reader explicitly re-asks.
- **Researcher exports** β import recorded cited-article references as BibTeX or RIS into Zotero,
and compare claim-level excerpts in a research evidence matrix with spreadsheet CSV.
Observed scholarly records include supplied authors/DOI/journal metadata and read limits;
missing fields stay explicit. See [researcher exports](docs/researcher-exports.md).
- **DOI and scholarly discovery** β resolve up to two exact Crossref DOIs from a question,
or opt into Crossref/arXiv searches. Read selected original publisher pages and bounded
versioned arXiv PDFs, with explicit abstract-only fallback. Metadata and public papers
carry no creator payout authority. See [scholarly research](docs/scholarly-research.md)
and the separate [proposed author opt-in payment plan](docs/paid-scholarly-papers.md).
- **Portable research receipts** β every permalink exports one deterministic JSON bundle containing
its answer hash, BUY/SKIP/CACHE decisions, exact article versions, claim evidence and sanitized
Circle settlement snapshot. Retain its SHA-256 to detect later changes; the self-check does not
pretend to be a Keryx, publisher, or on-chain signature.
- **Claim-aware evidence portfolios** β Keryx chooses a non-redundant set of positive source
proposals under separate attention and fetch-USDC caps. CACHE correctly costs zero fetch USDC but
one context slot; the receipt compares preview-predicted coverage with evidence yield after read.
- **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.
The [controlled offline paying-source study](docs/studies/paying-for-sources-2026-10-09.md)
runs the actual Keryx heuristic pipeline on four published fictional questions across
four budgets and three catalogue prices. Retained bodies, actual synthetic outputs,
literal/read-bound scoring and exact simulated ledger amounts are reproducible with
`npm run eval:paying-source-study -- --check`. It measures this closed fixture only;
live model behavior, semantic correctness, real spending and exploration's causal
effect remain unmeasured.
[Historical testnet records](https://keryx.cc/history/testnet) retain their original
network and settlement labels. The [current usage summary](#usage-so-far) keeps
mainnet and testnet reporting separate.
## Research tools and desktop
Windows local Operator alpha: `npm run desktop:install` then `npm run desktop:start`.
See the [desktop guide](docs/desktop-alpha.md) for the unpacked app build, offline
saved results, private Markdown briefs, and limits.
Developing in concurrent sessions: read the
[shared coordination workflow](docs/engineering/multi-session-coordination.md)
before editing or releasing, together with the
[validation and release gates](docs/development-workflow.md).
[Research-paper library](docs/paper-library.md): browse 40 observed paper records
from arXiv, OpenReview, PMLR and ACL Anthology, filter by author/year/DOI, or explicitly
search live arXiv/Crossref metadata. `/api/papers` and `npm run papers` share the
bibliography-only contract. Links remain unread until a separate research run.
[Literature workspace](docs/literature-workspace.md): save exact paper records on
this browser, screen against a review question, keep personal notes, export CSV/JSON/RIS
and prepare an editable two-paper comparison. No account, cloud sync or automatic ask.
[Research Monthly](docs/research-monthly.md): a bounded plan for four Deep
requests over 30 days, 10% below four separate packages with unchanged creator
caps. Manual renewal; no scheduling or unlimited use. Failed/pending jobs use a
slot. Web/API own the entitlement; Monthly CLI and MCP handoffs share that contract.
[Original-customer deliverable choices](docs/engineering/deliverable-acceptance-250.md)
source candidate: an ordinary settled prepaid A2A customer can Accept, request a
revision or Reject the exact retained delivery through its report, scoped API,
MCP or `npm run deliverable:acceptance -- read <a2a_id>`. Submissions use the exact
read-back fingerprint/digest/revision and a retained idempotency key. Reasons stay
private; sharing current choice/timestamp is opt-in and withdrawable. Historical
`remedy:none` and missing response-window terms remain visible. Revision/refund
execution is withheld; Monthly/private/browser/native originals and synchronized
deployment/distribution acceptance remain separate gates.
## For creators
- **Claim proven demand** β [keryx.cc/wanted](https://keryx.cc/wanted) shows claims paid
dispatches left under-covered. A new creator can check and list an RSS feed; an existing registry
creator can offer the exact indexed article directly and optionally sign a temporary discount.
Keryx guarantees that version a candidate slot, not a purchase, then queues one bounded retry
after refreshing creator authority. Fulfillment is public only when
that source passes the evidence gate and its citation reward really settles. Every claim has a
canonical shareable brief and social card, so the specific gap can reach the writer who covers it.
- **Onboard from your own wallet** β paste an RSS feed at [keryx.cc/register](https://keryx.cc/register)
and publish your source to the on-chain registry. Keryx sets up the x402-priced endpoint and
free preview; it never holds your key. On mainnet your wallet supplies native USDC
gas; the faucet is available only on testnet.
- **Own your payout** β your registered source pays the wallet you signed in with.
The first historically owner-verified testnet 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).
Seeded sample sources have Keryx-controlled registry authority; live authority and payout
checks are available on [`/proof`](https://keryx.cc/proof).
- **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** β your wallet signs a Gateway burn intent in the browser and
submits the reviewed mainnet mint with native USDC gas. Optional gas-relay operation
is a separate role; historical testnet cash-outs do not prove a mainnet withdrawal.
- **Keep everything** β 100% of every citation reward goes to creator wallets. 0% platform fee.
- **Squat-proof identity** β sources live in an on-chain SourceRegistry
with creator-scoped IDs and on-chain multi-author splits. Health on
October 16, 2026 reported V3
[`0x2217250019ab614dae7391d346d05c3fc4d71ae1`](https://explorer.arc.io/address/0x2217250019ab614dae7391d346d05c3fc4d71ae1).
The October 4 V1 registry
[`0x42a64061b6cd84067bb660b2a9b8aa881fd225bb`](https://explorer.arc.io/address/0x42a64061b6cd84067bb660b2a9b8aa881fd225bb)
remains the retained earlier authority. The recorded walkthrough payout
check still reads V1.
### Public sources and owner claims
Public web discovery finds supported websites, feeds and PDFs for the question at
hand and reads available content for free. `/sources` shows retained feeds and creator
listings, rather than a bulk index of the internet. A publisher can choose **This is
my source** or open `/claim-source`, sign in with its wallet, and prove control using
a dedicated website file or publisher-controlled RSS/Atom channel token.
Verification earns nothing by itself. Connect the exact owner-created registry listing
and explicitly choose free reads with no rewards, zero-price reads with qualified
citation rewards, or positive-price paid reads. Earning activation requires separate
distribution-rights consent and fresh control proof; registry registration is an
owner-reviewed network transaction with possible native gas, using no agent funds.
Control expires after 24 hours and earning eligibility pauses until explicitly refreshed.
Old public reference identities and free receipts remain free, and no activation bills
past uses. Zero-price reads require no x402 access authorization or settlement receipt.
The shared reading pipeline applies the same policy and evidence gates across web,
API and agent clients. Claim management uses the web and its authenticated API;
scholarly-rights enrollment remains separately gated. See the
[public-source claim guide](docs/public-source-claims.md) for proof, listing, policy
and recovery steps and deployment capability requirements.
## 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** β the caller-funded package uses its local Arc wallet to pay
Keryx's x402 toll before Keryx researches and pays creators. Version 0.3.2 requires
existing owner-provisioned custody, a trusted merchant policy and supported Node.
Use [verified package distribution](docs/mcp-distribution.md). October 3 discovery found
npm latest 0.4.1 and
GitHub v0.26.1 assets from `f9dca8d` are the previous immutable release. Application
0.26.2, caller MCP 0.4.2 and desktop 0.4.2 are coordinated claim-grounding candidates;
packed acceptance, exact-source installer checks and publication are separate gates.
Check verified release assets and npm integrity/provenance for current artifact status;
publication does not establish hosted deployment.
- **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. Versioned Quick/Deep packages pin the
execution contract and return provisional-SLO latency plus deterministic evidence-quality
receipts; see [`docs/a2a-research-packages.md`](./docs/a2a-research-packages.md).
- **OpenAI-compatible endpoint** β point any OpenAI SDK or tool (LangChain, LlamaIndex, OpenWebUI,
LibreChat, Continue) at `https://keryx.cc/api/v1` with model `keryx`: a drop-in Chat Completions
API. Free with no key, or pass a `kx_live_β¦` key as the Bearer token for higher limits. Every
cited creator is still paid downstream in USDC on Arc; with `stream:true`, the agent's live
buy/skip/trust reasoning streams as `reasoning_content` deltas. Try it with no install in the
[browser playground](https://keryx.cc/playground) β it also hands you the exact curl/Python/JS call.
- **Public API with wallet-issued keys** β SIWE-authenticated key minting (hashed, show-once,
rate-limited) and OpenAPI docs at [`/api/docs`](https://keryx.cc/api/docs).
- **Receipt export + local verification** β `GET /api/dispatch/<id>/receipt` returns the portable
research receipt; download it from any permalink and run
`npm run verify:receipt -- ./keryx-receipt-<id>.json` to recompute its payload digest. See the
[receipt format and trust boundary](./docs/research-receipts.md).
- **Non-custodial by design** β interactive spend uses a session EOA the *user* funds from their
own wallet; the browser co-signs each x402 authorization in-tab. The funded amount is the hard
cap. Keryx never holds your key or your funds.
- **The chain decides who gets paid** β before anything signs or settles, every payee is checked
against the on-chain SourceRegistry, not against Keryx's database. Editing the database cannot
reroute a single citation reward, on any path β browser or A2A.
- **Transparent treasury** β [`/api/treasury`](https://keryx.cc/api/treasury) publishes the
settlement wallet's chain-abstracted Gateway balance (via Circle App Kit), so anyone can audit
what backs the payouts.
- **Live activity feed** β [`/api/activity`](https://keryx.cc/api/activity) streams the most recent
real settled citations (source, question, reward) β a proof-of-life surface and a zero-prior-knowledge
way for tooling to see what Keryx is citing right now; it also drives the live ticker on the landing.
- **Answer archive as an Atom feed** β subscribe to [`/answers/feed.xml`](https://keryx.cc/answers/feed.xml)
and see every new paid answer as it settles. Keryx onboards creators by reading their RSS feeds;
this is the same door pointed the other way β Keryx itself becomes a source any reader or agent
can follow.
## The money rails
Live settled totals require Circle settlement evidence. Offline development runs are
labeled `SIMULATED`.
- **x402 pay-per-request** (`@circle-fin/x402-batching`) β a two-toll design: a small fixed
*access* toll to read, plus a dynamic *citation* reward priced by contribution weight. Fetched
but uncited earns the toll; cited earns proportionally more only after its evidence passes the
deterministic grounding gate.
- **Circle Gateway nanopayments** β batched sub-cent settlement (floor $0.000001). Historical testnet average
payment: ~$0.0044 β a true nanopayment, uneconomical on any card rail.
- **Treasury observation** β mainnet reads the sealed public role's Circle Gateway balance;
historical testnet used Circle App Kit (Unified Balance Kit). Current observation is published on
[`/status`](https://keryx.cc/status) and [`/api/treasury`](https://keryx.cc/api/treasury).
- **SourceRegistry contract on Arc** β source identity, IPFS CIDs, multi-author splits; on-chain
events drive the off-chain indexer.
- **Encrypted content on IPFS** β AES-256-GCM ciphertext pinned publicly; plaintext is released
only after x402 settlement verifies. Free previews stay plaintext.
- **USDC-native chain** β Arc settles in <500ms with USDC as gas, which is what makes per-citation
economics physically possible.
## Architecture
The [Circle and Arc integration ledger](docs/engineering/circle-arc-integration-ledger.md)
maps each integration to code, network, status and public proof. It also records the
gasless user-action evaluation and the sponsored testnet proof still required by #304.
Production uses **Arc mainnet (`eip155:5042`)**. A read-only
[/api/health](https://keryx.cc/api/health) check on October 16, 2026 reported
commit `2dda3717` and SourceRegistry V3. The October 4 launch observation
remains in [mainnet status](docs/mainnet-status.md), with the full constants
and the separation from historical testnet evidence.
| Role | Full public address | Explorer |
| --- | --- | --- |
| SourceRegistry V3, health October 16 | `0x2217250019ab614dae7391d346d05c3fc4d71ae1` | [Arc mainnet](https://explorer.arc.io/address/0x2217250019ab614dae7391d346d05c3fc4d71ae1) |
| SourceRegistry V1, retained October 4 authority | `0x42a64061b6cd84067bb660b2a9b8aa881fd225bb` | [Arc mainnet](https://explorer.arc.io/address/0x42a64061b6cd84067bb660b2a9b8aa881fd225bb) |
| Gateway Wallet | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | [Arc mainnet](https://explorer.arc.io/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE) |
| Gateway Minter | `0x2222222d7164433c4C09B0b0D809a9b52C04C205` | [Arc mainnet](https://explorer.arc.io/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205) |
Creator and user session addresses vary by workflow. The
[submission pack](docs/tameion-submission.md#public-addresses) also records public
USDC and Gateway contract references and the evidence required for actual payments.
```
BROWSER (Web App) IPFS + Arc Smart Contracts Circle Gateway + Arc Mainnet
βββββββββββββββββ βββββββββββββββββββββββββ ββββββββββββββββββββββββββββββ
ββββββββββββββββββββ [SourceRegistry]
β /ask page β (SIWE on Arc 0x42a640... USDC on Arc
β + wallet connect β auth) β’ sources[] (ERC-20, 6 decimals)
β β β’ emit Registry events
ββββββββββ¬ββββββββββ β’ indexed by off-chain DB
β session-grant
β (user funds session EOA) [IPFS Content]
β MetaMask tx β session β’ AES-256-GCM encrypted [Circle Gateway]
β deposits in Gateway β’ plaintext released only post-settle β’ batch settlement
β β’ x402 EIP-712 verify
β [Keryx API]
β co-sign loop (fetch+POST): β’ auth: SIWE JWT (browser + API key) [Arc RPC]
/api/ask (SSE) βββββββββββββββββββΆ /api/session/* (grant, credit) selected Arc mainnet RPC
browser streams /api/ask (agent asks, gets
sign-requests /api/ask/sign sign-requests back)
βββββββββββββββββββββββββββββββββ /api/source/[id]/item/[itemId]?version=β¦
client-side session key /api/offers (signed article price book)
/api/cite (citation reward)
signs EIP-712 /api/keys (API key mint/verify)
auto-signs (NO prompt) /api/agent/ask (A2A, x402-priced)
/api/treasury (App Kit unified balance)
/api/docs (OpenAPI)
Agent brain (lib/agent/run-agent.ts):
decomposeβdiscoverβdecideβfetchβsufficiencyβsynthesizeβattributeβsettle
```
## Run it
For project development, [the OSS AI adoption record](docs/engineering/oss-ai-adoption-2026-10-05.md)
documents checked upstream patterns and their Keryx acceptance gates. Use
[`$keryx-oss-adoption`](.agents/skills/keryx-oss-adoption/SKILL.md) for future
OSS learning and adaptation tasks in supporting development agents.
**One local developer command (~90s).** The final recorded demo is linked at the top of this README.
Decide β pay the x402 toll β read β synthesize β settle
weighted citation rewards, then report payments on the explicitly configured network.
The checked-in environment example is for isolated testnet development; mainnet
operations require the reviewed configuration and a finite authorized budget:
```bash
npm run demo -- "How do x402 and stablecoins enable AI agent commerce?" --budget 0.05
```
With `ANTHROPIC_API_KEY` + `AGENT_FUNDER_PRIVATE_KEY` + `NEXT_PUBLIC_KERYX_REGISTRY_ADDRESS` it
settles for real and prints on-chain proof; without them the same flow runs offline, clearly
labeled `SIMULATED` β a mock is never presented as settled.
```bash
# 1. Install (Node 22 LTS v22.19.0+ or Node 24+; CI and production use Node 24)
npm install --global npm@11.19.0
npm install
# 2. Configure (optional β runs offline with zero keys)
cp .env.example .env.local
# 3. Demo sources (offline development needs no wallet keys)
npm run seed-sources
# 4a. Hosted sponsored trial: no local wallet or provider keys, public report
npm run ask:sponsored -- --help
npm run ask:sponsored -- --public "How do source tolls differ from citation rewards?" --mode quick --budget 0.05
# 4b. Local engine, full reasoning trace in the terminal
npm run ask -- "How do x402 and stablecoins enable autonomous AI agent commerce?" --budget 0.05
# 4c. Or the full web app (SIWE auth, session grants, browser co-sign)
npm run dev # http://localhost:3939
# 5. Live metrics
npm run metrics
```
The legacy `generate-wallets` command is retired because it printed private keys
and replaced existing environment custody. For real operations, provision
secrets privately under the current role-specific labels and preserve existing
wallets and backups. Follow [treasury custody](docs/treasury-wallet-custody.md) or
[caller-owned buyer setup](docs/buyer-agent.md); starting a demo does not create or
recover a wallet.
The [sponsored client guide](docs/sponsored-client-research.md) covers the source
CLI, stdio MCP tool and native Desktop screen. They share hosted service limits;
the existing caller-funded buyer remains a separate choice. Published package
and installer availability must be checked independently of the source checkout.
| Mode | Reasoning | Payments | When |
|------|-----------|----------|------|
| **Offline dev** | heuristic, no LLM key | simulated, labeled | laptop, zero setup |
| **Server treasury** | Claude / DeepSeek | real Arc mainnet, dedicated sealed-policy custody | admitted hosted research and paid A2A |
| **User interactive** | Claude / DeepSeek | real Arc mainnet, user-funded session signer | production web app |
| **Isolated integration tests** | configured provider or fixtures | Arc testnet, separate keys/state | payment drills and development |
## Built to stay up
Keryx runs as a real service, not a demo that dies after the video:
- **Public [`/status`](https://keryx.cc/status) + [`/api/health`](https://keryx.cc/api/health)** β
uptime, deployed commit, settlement mode, live traction, treasury balance.
- **Low-downtime deploys** β new builds compile beside the live one, swap atomically, health-gate,
and auto-roll-back if the new build doesn't come up (`npm run redeploy`).
- **Treasury watchdog** β hourly cron checks settlement-wallet USDC + gas against thresholds and
alerts before settlements can stall; failed settlements alert immediately.
- **Rotating off-box backups** of the traction datastore, hourly.
- **CI** β typecheck + the economic-invariant suite on every push.
## Security
The interactive path is non-custodial. Its key security boundaries are:
1. **Circle facilitator** β x402 settlement batches through Circle's facilitator (no on-chain
alternative in the current Arc payment path).
2. **Server holds the IPFS decryption key** β content is encrypted at rest, but key release is
server-side (Lit Protocol planned once Arc is supported).
3. **Session key lives in a Web Worker** β derived there, never returned; the tab holds only
AES-GCM ciphertext under a non-extractable key. The worker signs payment authorizations to
registry-authorised payees only, and transactions only to USDC/Gateway β so page-level XSS can
neither steal the key nor name itself as payee. Residual: the derivation signature is produced
on the main thread, a one-call window at setup.
4. **Treasury gas wallet** β holds gas only, rotated; a compromise cannot touch creator funds.
Full threat matrix and verification results: [`docs/security-threat-model.md`](./docs/security-threat-model.md).
## Fork the primitives
The MIT-licensed [standalone Arc primitives](https://github.com/tang-vu/keryx-arc-primitives)
now have a reviewed **0.4.0 integrity and payment-terms refresh**, also pinned at
[`arc-primitives/`](./arc-primitives) (clone with `--recurse-submodules`).
- Exact micro-USDC parsing and weighted allocation, plus fixed/dynamic x402 settlement
with durable host admission and retained ambiguous outcomes.
- Creator-bound registry helpers and ordered, deduplicable indexing; the original
registry contract remains separate from current upstream v2 work.
- Atomic integer budget reservations as an explicitly **in-memory reference**, and
browser-signed, treasury-relayed withdrawal with finite authorization height,
exact attestation binding and journaled mint transaction identity.
- Additive discovery metadata, pinned Circle SDK/x402 dependencies, generated ESM/types,
a no-network demo and a clean packed-consumer check.
- Plaintext SHA-256/UTF-8 delivery checks retain payment evidence on delivery failure;
selected source-version registry checks bind the origin, payee and price.
The 116 tests and offline demo are synthetic; funded acceptance, durable storage,
browser custody, reconciliation and mainnet review remain host-owned gates. This
library release does not change Keryx's payment runtime, MCP package or desktop installer.
The built release is available as a GitHub tarball. See the
[standalone 0.4 migration guide](https://github.com/tang-vu/keryx-arc-primitives/blob/9690ee8fcabdd103b2bb4edfa0d588c80ca35f10/docs/migration-0.4.md)
and [maintenance and surface boundaries](docs/arc-primitives-maintenance.md).
## Project docs
- [`docs/engineering/source-catalog-2026-10-06.md`](./docs/engineering/source-catalog-2026-10-06.md) β expanded source library, publisher links, feed audit and discovery filters
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) β branch, pull request, validation and payment-safety workflow
- [`docs/rust-engine-migration.md`](./docs/rust-engine-migration.md) β staged shared Rust engine and acceptance gates
- [`docs/openai-compatible-api.md`](./docs/openai-compatible-api.md) β drop-in recipes for OpenAI SDK, LangChain, LlamaIndex, Open WebUI, LibreChat, Continue
- [`docs/system-architecture.md`](./docs/system-architecture.md) β data/money flow + on-chain components
- [`docs/security-threat-model.md`](./docs/security-threat-model.md) β threat matrix, audits, residuals
- [`docs/engineering/source-money-adversarial-2026-10-09.md`](./docs/engineering/source-money-adversarial-2026-10-09.md) β eight malicious-source classes, paid delivery checks and remaining live proof gates
- [`docs/codebase-summary.md`](./docs/codebase-summary.md) β module map
- [`docs/mainnet-delivery-plan.md`](./docs/mainnet-delivery-plan.md) β current product and release gates
- [`docs/project-roadmap.md`](./docs/project-roadmap.md) β near-term priorities
- [`TRACTION.md`](./TRACTION.md) β live usage and settlement links
- [`FEEDBACK.md`](./FEEDBACK.md) β Circle/Arc dev-tool feedback we filed while building
- [`DECISIONS.md`](./DECISIONS.md) β architecture decision log
## Origin & where it's going
Keryx has been developed by a solo builder since June 2026, beginning with creator
nanopayments and growing into a research service. A
[June 20 RSSHub discussion](https://github.com/DIYgod/RSSHub/discussions/22315)
proposed opt-in feed payouts; it records community outreach, with no upstream
adoption claimed. Development continued after Lepton, production moved to Arc
mainnet on October 4, and later user tasks shaped the writing and recovery tools.
The business direction is research deliverables for developers, researchers and
small teams, with eligible creators paid for supporting evidence. Prepaid research,
the hosted Operator and a bounded manual Research Monthly plan provide the
commercial workflow. The next validation goals are participant-funded repeat
demand and independent acceptance of a complete paid-business result. The
[roadmap](docs/project-roadmap.md) and [delivery plan](docs/mainnet-delivery-plan.md)
record the next work; the [event evidence](docs/tameion-submission.md) records progress.
**Arc community recognition:** Keryx received a shoutout from the Arc team at the
[Architect Check-in on October 16, 2026](https://community.arc.io/public/clubs/architects/events/architect-check-in-u1f8k3tkdy),
as one of approximately **3β4 projects shown** during the event, confirmed by the
owner. See the [recognition note](docs/tameion-submission.md#community-recognition).
*Keryx on screen at the October 16 Architect Check-In. Screenshot supplied by the
project owner.*
## Stack
Next.js 16 Β· React 19 Β· Tailwind 4 Β· shadcn/ui Β· viem/wagmi Β· `@circle-fin/x402-batching` Β·
`@circle-fin/unified-balance-kit` Β· `@x402/fetch` Β· Node `node:sqlite` / Supabase Β·
Rust / Tauri / WebView2 Β· Anthropic / DeepSeek. Built on the verified
[`circlefin/arc-nanopayments`](https://github.com/circlefin/arc-nanopayments) x402/Gateway plumbing.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessWithin a week