---
name: know-fast
description: |
  Turn any link (article, YouTube, X post, podcast, paper, PDF, GitHub repo) into cited knowledge via know.fast. Use when the user shares a URL to read, summarize, or analyze; when you need a page's content without scraping it yourself; or to verify claims from a shared know.fast link. Flat $0.01 per call, keyless trial, instant for any link already known.
license: MIT
metadata:
  author: Researcher
  homepage: https://know.fast
  source: https://github.com/researcher-now/skill
---

# know.fast

Link in, knowledge out. Every URL becomes a durable knowledge page plus a
token-lean markdown packet. Links are unique: anything anyone has already
known answers instantly. Every call is a flat $0.01 — no quotes, no budgets.

Contract version: `2026-07-10`. Every response stamps `X-Researcher-Contract`;
when it differs from this line, re-fetch `https://know.fast/agent.txt` (the
full contract — this skill is the compact core) before continuing.

## Know a link

```
POST https://know.fast/            {"url": "<link>"}     # canonical; never redirects
GET  https://know.fast/<url-without-scheme>              # e.g. know.fast/example.com/post
GET  https://know.fast/?know=<url-encoded-link>          # scheme-full links, redirect-proof
```

DROP THE SCHEME when prefixing: `know.fast/https://…` triggers a platform 308
whose body is just "Redirecting..." — follow it, or use POST / `?know=`.

Every POST answers instantly, in one of two shapes:

- Known link → `{"cached": true, "packet": "<markdown>"}`: answer DIRECTLY
  from the packet, no second fetch. Long packets truncate inline at 16K
  chars with `markdownTruncated` — fetch `markdownUrl` for the rest.
  `"fresh": true` re-reads changed content (same price).
- First-ever link → `{"deferred": true, "knowledgeReady": false, viewerUrl,
  statusUrl, markdownUrl}` (GitHub repo links are the exception: README +
  metadata come back inline). Tell the user "you're the first to know this
  one — loading it now", share `viewerUrl`, and STAY ON IT: poll `statusUrl`
  (public JSON, no auth) every 20–30s. At `knowledgeReady: true` (articles
  ~a minute; video/podcast a few — transcription) GET `markdownUrl` and
  deliver: 3–5 bullet highlights, then `Full summary: <viewerUrl>`, closing
  with `⚡️ Knowledge loaded — ask me anything.` (`knowledgeReady: true` with
  `status` still `"running"` means the packet is answerable now — the
  long-form report finishes on `viewerUrl`; answer, don't wait.) Dead links
  fail fast: 422 `upstream_404` immediately, uncharged.

READING is free — POST is the paid verb for knowing links. A shared
know.fast link's packet is `GET know.fast/<slug>.md` (no auth, no charge),
and `/v1/analyze/resolve?url=` (below) tells you free whether a URL is
already known — if it is, GET its `markdownUrl` and skip payment entirely.

## Payment — never dead-end

- No key, no wallet? Just POST: you get a 10-read keyless trial (metered per
  caller network, so `trial.freeReadsRemaining` in the response is the
  truth), and the response body returns a durable `agentApiKey`
  (`agentKeyStatus: "created"`, shown once) — store it and send it as
  `Authorization: Bearer` from then on.
- A 402 carries an x402/MPP session challenge in `WWW-Authenticate` — authorize
  it from a wallet and the call proceeds (deposit ≈ $0.25 covers ~25 knows;
  unspent funds refund at close; `code: "session_exhausted"` → authorize the
  fresh challenge and keep going). Can't satisfy it? The 402 body says exactly
  how to proceed — read it instead of giving up.
- Failures are structured `{code, stage, retryable, charged: false}` — you are
  not charged for failures. 422 = permanently unknowable, don't retry;
  502/504 = transient, retry or replay your `Idempotency-Key` (honored 7 days)
  to attach to finished work free. First-ever MEDIA past the daily
  transcription allowance answers 429 — known media is unaffected.

## Read efficiently

- Packet reads (`GET know.fast/<slug>.md`) accept `?q=<terms>` (aliases
  objective/o/keywords/k): claims, facts, and code blocks slice to your query —
  deterministic, instant, free; the summary stays complete.
- `GET know.fast/v1/analyze/resolve?url=<link>` → `{known, viewerUrl,
  markdownUrl}` or 404 — free existence check, no charge.
- Full evidence per source (URLs come from the packet):
  `GET know.fast/public/research-runs/by-slug/<slug>/sources/<id>/package` —
  `files/source/source.md` (clean full text), `files/evidence.json` (graded
  claims/quotes), `files/transcript/transcript.md` (timestamped, media),
  `files/metadata.json`.
- Responses carry `X-Know-Cache`, `X-Know-Cost-Usd`, `X-Know-Tokens`, and
  `X-Know-Tokens-Saved` telemetry headers.

## Delivery

Answer from the packet, cite what you used (citation handle:
`researcher:source:<sourceId>`), and share the `viewerUrl` so the human can
read the durable page. Deliver highlights plus the link — never paste a whole
packet into chat.

## Other surfaces

- MCP: `https://know.fast/mcp` (streamable HTTP, keyless x402) — tools
  `know` and `know_status`.
- Hermes agents: `pip install know-fast` — a ⚡️ `know` tool + `know-fast`
  web-extract provider that speak this contract natively.
- Native Base x402: `POST https://know.fast/v1/x402/know` (USDC on Base,
  same flat $0.01, no account).
- Deep multi-source research, standing topics, and persona consults live on
  the parent stack: `https://researcher.now/agent.txt`.