# know.fast — agent contract Contract-Version: 2026-07-10 Send a link. Know it. know.fast turns any URL (article, YouTube, X post, podcast, paper, PDF) into a durable knowledge page plus a token-efficient markdown packet built for agent relay — and links are unique, so anything anyone has ever known answers instantly. Every call is a flat $0.01. ## Fastest path: prefix any URL GET https://know.fast/ e.g. curl know.fast/example.com/post GET https://know.fast/?know= (alias ?url=; scheme-full is fine here — URL-ENCODE the value or a & in the link truncates it) DROP THE https:// WHEN PREFIXING: a scheme in the path (know.fast/https://example.com/…) triggers ONE platform 308 redirect whose body is just "Redirecting..." — if your fetch tool does not auto-follow redirects you will read that as the result. Follow the redirect, drop the scheme, use the ?know= query form, or POST (below) — POST never redirects. Known OR unknown, the GET IS the analyze call — same flat cent, same keyless trial, same 402 payment challenge and response shapes as the POST below. A known link's packet comes back directly as markdown (no redirect hop), with your key/trial status in a short coda after a `---` rule. The URL's own query string (e.g. youtube.com/watch?v=...) is preserved. Do NOT append .md to the TARGET url (that suffix belongs to packet slugs, know.fast/.md) — if you do, and the un-suffixed link is already known, you get its packet anyway instead of a 404 analysis. ## The whole flow 1) POST https://know.fast/ (aliases: /v1/know, /v1/analyze) Content-Type: application/json Body: {"url": "", "lang": "en"?, "fresh": true?} EVERY CALL ANSWERS INSTANTLY. LINKS ARE UNIQUE. A link anyone has already known answers with the knowledge inline, for the same flat cent: {"cached": true, "knowledgeReady": true, "packet": "", viewerUrl, markdownUrl}. When `packet` is present, ANSWER DIRECTLY FROM IT — no second fetch needed. Pass "fresh": true to re-read changed content (same price). First-ever links get known once, for everyone — and STILL answer instantly, with the run reference instead of the packet: {"deferred": true, "knowledgeReady": false, "viewerUrl": ..., "statusUrl": ..., "markdownUrl": ...}. Reply to your user right away and share viewerUrl; the knowledge follows (see 2). - Articles (text-only X/Twitter posts and threads included) usually land in about a minute. - Video/podcast takes longer (transcription, 2-8 minutes). Only X posts that actually contain video count as video. - GitHub repo links return the README + repo metadata (clean, chrome-free), and code-repo packets include the repo's verbatim quick-start commands. PDF/arXiv links resolve to the real document title. Inline packet markdown caps at 16K chars with markdownTruncated/markdownNote pointing at markdownUrl. - Dead links still fail fast: a URL whose server answers 404 returns 422 {"code": "upstream_404"} immediately — uncharged on the flat-fee rails (see Failure semantics; x402 settles before the call, as always). 2) Deferred runs — you're the FIRST to know this link. STAY ON IT: - A deferred run means nobody has known this link yet, so it takes a little longer than usual (already-known links answer instantly). Immediately tell the user just that ('you're the first to know this one — it'll take a little longer than usual') and share viewerUrl. "It's processing" is not an answer — stay on it. - Poll the response's statusUrl every 20-30s — public JSON, NO auth needed (it's /public/research-runs/by-slug/?include=summary) — do not end your turn while it runs. (Or poll GET https://know.fast/v1/runs//job with your agentApiKey — the run is owned by your wallet's account.) - The moment {"knowledgeReady": true} (typically 1-3 min — transcript + claims land before the long-form report), fetch the response's markdownUrl (GET https://know.fast/.md) and DELIVER THE KNOWLEDGE: 3-5 bullet highlights, then "Full summary: ", then close on its own line with "⚡️ Knowledge loaded — ask me anything." The finished report lands on the same page at {"status": "succeeded"}. The packet: title, source URL, summary, key claims/facts inline, and pointers into the knowledge files below (only files that actually exist are listed). Answer directly from it. ## Knowledge files (per source, from the packet) GET https://know.fast/public/research-runs/by-slug//sources//package - files/source/source.md clean full text - files/evidence.json graded claims / facts / quotes - files/transcript/transcript.md timestamped transcript (media) - files/metadata.json creator, type, word count, citation handle The package URL itself returns the manifest (all files + sha256). ## Auth + payment - ONE CENT FOR EVERYTHING: every POST — known link, first-ever article, even first-ever video/podcast (we absorb the transcription cost) — is a flat $0.01. No quotes, no budgets, no surprises. - No wallet, or nothing it can spend? Just POST a link — you can start reading right away; the response returns an agentApiKey to reuse (send it as Authorization: Bearer). Never dead-end on a payment challenge you can't satisfy: even a trial-exhausted 402 carries a fundable agentApiKey (if you don't already hold one) plus a `funding` object — GET /v1/account with that key to get depositChains[].depositAddress, have your human deposit USDC (Base) or stablecoin (Tempo) there (even $1 ≈ 100 reads), and keep reading with no payment headers. - Pay from a wallet (the 402 carries an x402/MPP session challenge; authorize it and the call proceeds), or use a funded key. The session challenge suggests a work-session deposit — clamp(price x 25 calls, [price, $10]), so $0.25 here — one channel covers ~25 knows; the deposit settles to what you actually spent when the channel closes and unspent funds are refunded. An exhausted channel answers 402 with code: "session_exhausted", an action string, and a fresh challenge in WWW-Authenticate — authorize it and keep going. - Your first paid call returns a durable key IN THE RESPONSE BODY: agentApiKey, with agentKeyStatus: "created" and an agentApiKeyNote — store it and send it as a Bearer token. Raw keys are shown only once, at mint; if your wallet already has a key you get agentKeyStatus: "existing" plus agentKeyPrefix instead. (X-Researcher-Agent-Key rides the response headers as a secondary channel.) - Never-before-seen MEDIA links draw from a daily transcription allowance (per caller + global); past it the POST answers 429 until the next UTC day. Known media is unaffected. ## Failure semantics A failed know returns a structured body: code (stable: unsupported_site, upstream_404, no_content, unresolvable_media, fetch_failed, timeout, analysis_failed), stage, retryable, and charged. HTTP 422 = the URL permanently cannot be known — don't retry. 502/504 = transient — retry shortly, or replay your Idempotency-Key to attach to finished work free. You are NOT charged for failures on the know.fast flat fee (charged:false). Dead links are cached: re-knowing a permanently-failed URL answers instantly from cache (cached:true) and costs nothing; the verdict expires within a day, or pass {"fresh": true} to force a paid re-probe. ## Token efficiency - Packet reads (GET https://know.fast/.md) accept ?q= (aliases: objective, o, keywords, k): claims, facts, and code blocks are sliced to entries matching your query — deterministic keyword slicing, instant, no extra cost. The summary stays complete; a query matching nothing returns the full packet. Resolve a URL to its page without reading (free, no charge): GET https://know.fast/v1/analyze/resolve?url= → {known, viewerUrl, markdownUrl} or 404. - Responses carry telemetry headers: X-Know-Cache (hit|miss), X-Know-Cost-Usd, X-Know-Tokens (estimated tokens of the body), and X-Know-Tokens-Saved (vs reading the stored full source text). ## Notes - Idempotency-Key header is honored for 7 days — safe to retry. - Every knowledge page is a durable, citable run; citation handle format: researcher:source:. - MCP: connect to https://know.fast/mcp (streamable HTTP, keyless x402 supported) — the server identifies as know.fast. - Native Base x402 clients: POST https://know.fast/v1/x402/know (same body, same flat $0.01, USDC on Base via the standard 402/X-PAYMENT flow — no account, no key needed). Known links answer instantly with the packet; first-ever links defer with statusUrl/markdownUrl. Discoverable on the x402 Bazaar and agentic.market. - Hermes agents: `pip install know-fast` (PyPI) registers a ⚡️ `know` tool and a `know-fast` web-extract provider that speak this contract natively, including the deferred-media polling above. - Installable skill: https://know.fast/SKILL.md is the compact core of this contract for Hermes/Claude-style skill loaders (also on npm as @researcher-now/know-fast-skill and in github.com/researcher-now/skill). - Deep multi-source research, standing topics, and persona consults live on the parent stack: https://researcher.now/agent.txt ## Staying current Every response stamps X-Researcher-Contract. When it differs from the Contract-Version at the top of this file, re-fetch this file — response fields are authoritative over your cached notes. Installed clients (the know-fast pip plugin) send X-Researcher-Client-Version and every response answers with X-Researcher-Client-Latest plus, when you are behind, an X-Researcher-Upgrade header carrying the exact upgrade command — run it. A client below the published minimum gets HTTP 426 with the same command in the body. (X-Researcher-Min-Plugin on responses versions the PARENT stack's researcher-now pip package, NOT know-fast — the know-fast minimum lives in the discovery doc below and in 426 bodies; ignore that header here.) Hosted surfaces (this HTTP API, the MCP server) are always the latest version by construction — nothing to update. Machine-readable version discovery: https://know.fast/.well-known/know-fast.json