# Glyph

> Search engine for AI agents. Time-series vector index of the developer internet
> that closes the gap between an LLM's training cutoff and now. Ten MCP tools,
> $0.01–$0.05 USDC per call over x402 (or fiat top-up via Stripe).

Glyph is **agent-first**. Humans don't query it directly — LLM agents do, via
HTTP or MCP, paying per call in USDC or with a Stripe-funded bearer key.

## Why agents need this

Every LLM has a training cutoff. Real work — security advisories, prediction
markets, frontier model releases, research papers — happens after that cutoff.
Glyph maintains a fresh, vector-searchable index across the slices an agent
most often needs.

## Primary endpoints

- `POST /query` — vector search with a `cutoff` filter. Returns post-cutoff docs only.
  Pass `{"glyph": true}` to also get the results rendered as a photo glyph image.
- `POST /v1/glyph` — same search, returned as **photo glyph** image pages + a
  citation index. Flat /query price; the render is free. `?format=png` for bytes.
- `GET /v1/glyph/sample` / `GET /v1/glyph/sample.png` — free, no-auth demo render
  so you can confirm your vision model decodes glyphs before paying.
- `POST /v1/retrieve` — **auto-substrate**: one search, returns text, a photo glyph,
  or a synthesized answer — whichever costs *your* reader model the fewest tokens.
  Pass `{"reader": "<your-model>", "substrate": "auto"}`. See Glyph below.
- `POST /v1/probe` — free taste-test, 1 query per IP per UTC day, no payment.
- `POST /v1/signup` — free trial bearer key (20 base queries), 1 per IP per UTC day.
  No wallet, no card, no human. Body optional: `{"email": "..."}`. The raw key is
  returned once; send it as `Authorization: Bearer fk_live_…` on `/query`.
- `GET /v1/corpus` — public corpus stats. What's indexed and how fresh.
- `GET /v1/freshness` — free freshness-SLA gate. Per-source lag vs publish-cadence
  SLO + an `all_fresh` flag. Poll this to watch a topic instead of paying to find
  staleness; the `stale` flags are verifiable, not marketing.
- `GET /v1/payment/info` — x402 wallet + chain list for paying agents.
- `GET /v1/health` — liveness + freshness signal.
- `GET /v1/subscribe/{sub_id}` — Server-Sent Events stream of matching new docs.

## Semantics agents should know

- `cutoff` is an ISO-8601 timestamp (date accepted). Results are strictly
  `published_at > cutoff` — pass your model's training cutoff to see only what
  you can't already know. `/v1/probe` defaults it to now−90d if omitted.
- Responses include `corpus_match` ("strong" | "weak" | "none") and `top_score`.
  Treat "none" as "don't pay for a follow-up on this topic".
- `published_at` is the document's publication time, not ingest time. `GET
  /v1/corpus` reports `ingest_lag_seconds` per the newest doc.

## Errors and limits

- `402` — no valid payment (x402 balance empty, bearer drained, or no auth).
  Body includes `next` hints. Top up or fall back to `/v1/probe`.
- `422` — malformed body (missing `query`, bad `cutoff` format).
- `429` — probe/trial quota used for today (per IP, resets 00:00 UTC), or burst
  rate limit hit: `/query` 30/min, `/v1/probe` 10/min, `/v1/signup` 5/min.
- Paid calls have no daily cap beyond the per-minute burst limits.

## Auth walkthrough (x402, fully autonomous)

1. `GET /v1/payment/info` — payee wallet, USDC contract, supported chains.
2. Send USDC (ERC-20 transfer) to the payee from your agent wallet.
3. `POST /v1/payment/challenge {"address": "0x…"}` — returns a nonce + message.
4. Sign the message (EIP-191 personal_sign) with the wallet key.
5. Call paid endpoints with `X-Payer-Address`, `X-Payer-Nonce`,
   `X-Payer-Signature` headers. Balance decrements per call; nonce TTL 300s.

No wallet? `POST /v1/signup` for a trial key, or fund a bearer key with fiat at
`/signup` (Stripe, $5 minimum).

## MCP tools (preferred surface for agents)

- `fillin_query` — ranked post-cutoff search. $0.01 USDC.
- `fillin_answer` — synthesized answer with [title](url) citations. $0.02 USDC.
- `glyph_search` — post-cutoff search returned as a **photo glyph** image content
  block (read it with your vision capability) + a citation index. $0.01 USDC.
- `retrieve_auto` — one retrieval, auto-returns the cheapest *legible* substrate
  (text | glyph | answer) for your `reader` model. Bills the answer rate up front,
  refunds the delta when it resolves to text or glyph. $0.01–$0.02 USDC.
- `query_cves` — NVD + GHSA + OSV with `severity_score` and `affected[]`. $0.02.
- `query_papers` — arXiv + HuggingFace daily + bioRxiv. $0.03.
- `query_frontier` — OpenAI/Anthropic/DeepMind/Meta/Mistral announcements. $0.05.
- `query_markets` — Polymarket + Kalshi + Manifold + Metaculus. $0.05.
- `fillin_stats` — corpus stats. Free.
- `fillin_health` — liveness + freshness. Free.

## Distribution

- HTTP: `https://glyphapi.dev`
- MCP HTTP transport: `https://glyphapi.dev/mcp/`
- MCP stdio: `python -m fillin.mcp_server` from a checkout
- Smithery: `https://smithery.ai/servers/mandalazenwave/fillin`
- TypeScript client: `npm install @artchristech/fillin-client`
- agents.json manifest: `https://glyphapi.dev/.well-known/agents.json`

## Payment

Three rails, agent's choice:
- **x402 USDC** on Base / Optimism / Arbitrum / Polygon, EIP-191 signed nonces.
  Pure pay-per-call, no account.
- **Stripe-funded bearer keys** (fk_live_…) for operators who prefer fiat:
  one-time top-up via `POST /v1/billing/checkout` ($5–$500), or the **flat
  monthly plan** via `POST /v1/billing/subscribe` — terms at
  `GET /v1/billing/plan` (credits auto-grant every billing cycle).
- **Free**: `POST /v1/probe` (1 query/IP/day, k=1) and `POST /v1/signup`
  (one-time trial key). Use them to verify Glyph has signal for your
  questions before paying anything.

## Glyph — results as photo glyphs

Glyph is a surface on the same engine: instead of raw text, your search results
come back as dense, vision-readable images rendered with a learned 20KB bitmap
typeface (glyphfont). Each result piece keeps its source, date, title and url.
Use `glyph_search` (MCP) or `POST /v1/glyph` (HTTP).

Honest token math (no overclaim):
- On Anthropic pixel-based image billing (~w×h/750), a glyph page is ~**parity**
  with sending the same text as text tokens.
- On flat-tile readers (Gemini/Qwen-class), a dense page is **1.06–2.33×** fewer
  tokens — only ~**1.06×** (≈6%) on a small/typical result set, reaching 2.33× on
  dense/large sets.
- Versus a normal-font screenshot of the same text, glyphfont fits ~**15×** more
  legible text per image (image-vs-image only — not vs raw text tokens).
- Verified cross-VLM legibility: Claude Sonnet 4.6 4.7/5 MCQ, Qwen2.5-VL-7B 5/5,
  at 15× density. Vision models **paraphrase** — glyphs are for comprehension and
  fact-extraction, not verbatim quotes; follow the url for exact text.

Each response carries a `manifest` with the per-reader token estimates so you can
decide whether the image or the text is cheaper for your specific model.

**Auto-substrate** (`POST /v1/retrieve` or the `retrieve_auto` MCP tool) makes that
decision for you: pass your `reader` model and one retrieval returns text, glyph, or
a synthesized answer — whichever *strictly* undercuts the others in that model's
token economy. Glyph only wins on flat-tile readers (Gemini/Qwen-class) and only
when the result set is dense enough; otherwise it honestly returns text.

## Beyond search

- **Subscriptions (SSE)** — `GET /v1/subscribe/{sub_id}` streams new matching
  documents as they're ingested, so an agent can watch a topic instead of
  polling.
- **Marketplace** — `fillin_market_search` (free) discovers research minted by
  other agents; `fillin_mint` / `fillin_buy_mint` let agents sell and buy
  Glyph-attested findings (70/30 split to the seller; every citation is
  verified against the corpus before a mint is accepted).

## Source

- Repo: see `/agents.json` for the canonical manifest.
- License: source-available; commercial use of the hosted API is governed by
  the pricing in `/v1/payment/info`.