Turn any folder of markdown into a paid, cited retrieval endpoint: agents POST a question, pay per query over x402, and get back the most relevant passages with source citations. The agent-native way to sell knowledge — answers, not documents.
corpus (md files)
│ x402pkg package — sanitize → chunk by heading → FTS index
▼
artifact (.x402pkg) — single SQLite file: chunks + manifest + BM25 search
│ scripts/serve.ts — Hono runtime, POST /:id/search
▼
paid queries — cited passages, rate-limited, idempotent
Retrieval is SQLite FTS5/BM25 with OR-semantics for natural-language questions — zero model calls, zero API keys, deterministic, ~zero marginal cost per query.
pnpm install && pnpm build
npx tsx packages/cli/src/cli.ts package ./my-corpus \
--out artifacts/my.x402pkg --id my --title "My Corpus" \
--price 0.02 --pay-to 0xYourAddress --network eip155:8453The packager sanitizes on the way in (frontmatter/secret stripping) and chunks by heading; inspect and export-manifest commands examine an artifact.
Standalone (the runtime handles x402 itself — verify → retrieve → settle, replay-protected, per-client rate limits):
ARTIFACTS=artifacts/my.x402pkg PORT=8403 npx tsx scripts/serve.tsBrains-only behind a paying gateway (recommended): payments off, bind localhost, and let an x402sandbox proxyUrl product sell it — the gateway contributes settlement, request logging, the 402→paid conversion funnel, redelivery grace, and Bazaar discovery; this runtime only retrieves.
ARTIFACTS=artifacts/my.x402pkg PORT=8403 PAYMENTS_DISABLED=1 npx tsx scripts/serve.ts// gateway products.json
{ "sku": "ask-my", "title": "Ask My Corpus (per query)", "price": "$0.02",
"route": "POST /ask", "proxyUrl": "http://127.0.0.1:8403/my/search",
"discoverable": true }Never expose a PAYMENTS_DISABLED runtime publicly — it's for localhost behind a gateway, nothing else.
curl -X POST http://127.0.0.1:8403/my/search \
-H "content-type: application/json" \
-d '{"query": "why do insects attack low brix plants", "top_k": 5}'
# → { "corpus_id": "my", "query": "...", "results": [ { "text": "...", "source_file": "Brix.md", ... } ] }Free per-corpus metadata at GET /:id/.well-known/x402; health at GET /healthz.
- HTTP API — routes, request/response shapes, status codes, serving modes
- The .x402pkg artifact — manifest schema, chunking, versioning
- Security model — sanitization guarantees, money-path invariants, what buyers can extract
pnpm monorepo: packages/core (sanitizer, chunker, artifact/FTS, runtime, sales log, idempotency) · packages/cli (x402pkg command) · scripts/serve.ts (serving entry). pnpm test (58 tests) · pnpm -r typecheck · pnpm build.
BUILDLOG.md is the honest record: why this tool exists at all (a 37MB PDF that settled on-chain and then failed to deliver taught us agents buy answers, not documents), the FTS AND-vs-OR bug that made natural-language questions return nothing, the near-disaster of almost scaffolding a new project on top of this one, and the CI failure that died before it ever ran a test. Short, but every entry is a lesson that shaped the design.
P0–P2 complete (package → artifact → paid serving) + gateway-proxied mode; running in production serving the AfrEcoSoil soil-biome corpus (298 chunks) behind x402.inkypyrus.com/ask. Roadmap: embeddings/hybrid retrieval, RAG answer synthesis (Tier B), multi-corpus catalogs.
MIT