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 mainnet](https://img.shields.io/badge/settles_on-Arc_mainnet-1f1f1f)](https://docs.arc.io)
[![payments: Circle x402](https://img.shields.io/badge/payments-Circle_x402-2775CA)](https://github.com/circlefin/arc-nanopayments)
[![CI](https://github.com/tang-vu/keryx/actions/workflows/ci.yml/badge.svg)](https://github.com/tang-vu/keryx/actions/workflows/ci.yml)

Keryx is a citation-toll reading agent for researchers and builders: a question and
budget lead to a cited report, visible BUY/SKIP/CACHE decisions, and payment receipts
for eligible creator rewards.

**[Live app](https://keryx.cc)** · **[Public proof](https://keryx.cc/proof)** ·
**[Archived QA walkthrough (2m40s, app 0.27.43, recorded Oct 8)](https://github.com/tang-vu/keryx/releases/download/v0.27.43/keryx-current-release-6e591603-archived-qa-05.mp4)**.
Reopens an archived first-party report and receipt; no new research was submitted.
See the [recording scope and public checks](docs/reviewer-start.md#recording-gate).

## Try it in two minutes — no wallet

1. Open this [existing English cited report](https://keryx.cc/dispatch/b144ef47-c2f5-46ec-bdb7-e62bc1314913)
   about how source-access tolls differ from citation rewards. Read the summary
   and its `[S1]` source excerpts, including the Low confidence boundary.
2. Expand **Decision log** below the answer. Inspect why Keryx reused the cached
   first-party article and skipped unrelated candidates. This run has CACHE/SKIP
   decisions; it did not pay a new access toll.
3. Open **View JSON** in **Portable research receipt**, or use the
   [direct receipt](https://keryx.cc/api/dispatch/b144ef47-c2f5-46ec-bdb7-e62bc1314913/receipt).
   Under `payload.settlement`, check `mode: real`, `ledgerCompleteness: complete`,
   **0 USDC access / 0.025 USDC citation**, and the mainnet Circle reference.
   [Receipt verification and the retained digest](docs/reviewer-start.md#verify-the-example)
   explain what these records prove.

This is an archived owner-operated QA result using **Keryx Engineering (first-party)**,
not a fresh answer or an outside customer's task. The location/job in its prompt is
a test persona. It supports the three core payment facts but omits the requested
document revision, so the original deliverable remains partial. Opening the report
or receipt makes no research or payment request.

**Next, ask your own question:** open [keryx.cc](https://keryx.cc), choose Quick,
and submit a shareable question. The public sponsored trial needs no wallet or
sign-up; the composer shows the payer and budget. Admission depends on current
quota, available capacity and spend caps, so a new answer within two minutes is
not guaranteed. Submitted questions become public reports. See
[sponsored trial limits](docs/sponsored-research-trial.md).

## Usage so far

Read-only snapshot of [public metrics](https://keryx.cc/api/metrics),
**October 8, 2026, 16:24 UTC**, with [public health](https://keryx.cc/api/health)
reporting Arc mainnet / real settlement at `3b839ccd`.

| Measure | Observed value | Counting boundary |
| --- | --- | --- |
| Recorded research runs | 50 | All caller origins, including team and QA; not accepted deliverables |
| Settled payment records | 7 | All payment kinds; pending, failed and simulated excluded |
| Settled volume | 0.095 USDC | Gross payment volume, not net revenue |
| Creator access + citation payouts | 0.065 USDC to 2 earning creators | Includes first-party recipients; not independent creator adoption |
| Settled operating fees | 0 USDC | Reported separately from creator rewards |
| Outside users / team / QA | Separate counts unavailable | The endpoint does not partition these groups; guest questions are not unique outside users |
| Historical Arc testnet | Separate evidence only | Not included in these mainnet totals; see the [event-period record](docs/tameion-submission.md#event-period-usage-testnet-week-then-mainnet) |

These are dated database projections. [Live Ledger](https://keryx.cc/dashboard)
and [Public Proof](https://keryx.cc/proof) expose the current records and their limits.
The [submission pack](docs/tameion-submission.md#named-external-user-hoàng-freelance-developer)
separately documents sponsored outside use on testnet and unmatched participant
stories; none is inferred from these aggregate counts. [Snapshot hashes](docs/reviewer-start.md#public-checkpoint)
retain the exact observation.

## What is real and what is scripted

- **The two-minute path reopens a stored run.** Its model-written answer, decision
  trace and receipt are recorded artifacts. It is a curated QA example, not a live
  rerun or evidence of customer acceptance.
- **The example's payment is recorded as real Arc mainnet settlement:** one
  0.025 USDC citation reward to the first-party Engineering source. Its cached read
  cost zero. The Circle transfer reference is not a per-citation Arc transaction hash.
- **First-party and public sources are distinct.** Keryx Engineering and Keryx owner
  release notes are first-party validation sources. Public web/paper references
  alone grant no creator payout rights. Historical seeded sample sources have
  Keryx-controlled authority; they do not establish independent seller adoption.
- **CLI demo, seed and benchmark commands are scripts.** Offline development uses
  labelled simulated payments. Invoking a real-mode script can make actual paid
  requests; it is not required for the wallet-free review path.
- **Production research is caller-driven.** The local desktop alpha is not an
  autonomous scheduler. Monitoring/reconciliation jobs are operational checks,
  not independent users or fresh research. This public checkpoint does not verify
  the host's current schedule inventory.
- **Settlement is checked per receipt.** Pending, failed, simulated and planned
  amounts are separate from settled value. A cited answer, healthy API or script
  completion alone does not prove a payment settled.

## What happened during Tameion

The pre-event main baseline is
[`2291753` (September 25)](https://github.com/tang-vu/keryx/tree/2291753cc4fff2135d546227d5aafda287cbed7d).
During the event Keryx added original-document and scholarly discovery, portable
cited-report exports, a local CLI/Windows task workspace, bounded manual Research
Monthly, and prepaid Operator recovery/observation. Production moved from Arc
testnet to mainnet on October 4. The
[event-period product delta](docs/tameion-submission.md#event-period-product-delta)
links source evidence and the limits of each change.

The usage record separates the event's testnet phase from mainnet; the mainnet
snapshot above includes internal activity. Sponsored outside use is documented,
but independent paid demand, repeat use and general deliverable usefulness remain
separate evidence gates. Source candidates beyond the observed deployment are
not claimed live. The dated archived-QA walkthrough above reopens existing artifacts; it is not a
live-Ask or complete current-feature demonstration.

---

## 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** 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).

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