# Nostr Agent Onboarding > A curated knowledge base about the Nostr protocol, written for AI agents: what Nostr is, how it should work, how to develop and design for it, proven patterns with their failure modes, vendored primary sources, and the voices that shape it. Plain Markdown throughout. Read https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md first: it has the rules an agent must not break and a task router. For one-shot ingestion use https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms-core.txt (essentials, ~120 kB) or https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms-full.txt (everything, ~510 kB). Snapshot 2026-10-10; facts are dated inside each document. References to `~/…` paths and `localhost` services describe the author's workstation, not resources you can reach. ## Start - [Start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md): the briefing — Nostr in one paragraph, rules, task router, caveats, provenance ## Core synthesis - [Overview of the synthesis](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/00-overview.md): What the synthesis is built from, its reading order, the key disagreements, and the one-paragraph version of Nostr. - [01 · What Nostr is](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/01-what-nostr-is.md): Events, kinds and kind classes, relays, NIPs, what Nostr is not, why not ActivityPub/SSB/Pubky/Bluesky, vocabulary. - [02 · How Nostr should work](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md): The routing problem, the outbox model and its limits, relay hints, spam, no-global, the local relay, the failure model. - [03 · How to develop for Nostr](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md): Build pieces not platforms, the dev loop, tooling, onboarding, keys and signing, fault tolerance, anti-patterns, definition of done. - [04 · How to design on Nostr](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md): Schema then class then routing then failure model; kind allocation, privacy, communities, value-for-value, trust, arbitrating principles. - [05 · The current frontier (late 2026)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/05-current-frontier.md): Relay feeds, Blossom/nsites/Zapstore, signers, key rotation, provable time, Nostr as network identity, the AI convergence, open problems. ## Design layer - [Design synthesis](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md): The codified design rules: relay-feed vs outbox vs gossip, per-kind routing, kind taxonomy and decision rule, philosophy. - [Kind cheatsheet](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md): 30-second recipe for picking or evaluating an event kind, plus the common tag list. - [Known issues and measured gotchas](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md): Relay/Blossom/nak quirks found in practice: CORS, Khatru eviction, NIP-34 a-tag rejection, signer relay rot, the nsite trap set. ## Patterns - [Pattern · Signer login (NIP-07 / NIP-46 / NIP-55)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md): The three-keys model, per-method checklists, current wire formats, relay probe results, library bugs, definition of done. - [Pattern · Go baseline: fiatjaf.com/nostr](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/go-client-baseline.md): Why go-nostr/khatru/eventstore moved into fiatjaf.com/nostr, the package map, API changes, the toolchain trap, what not to use stock. - [Pattern · Testing a Nostr project](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/testing.md): Which relay to test against, the four altitudes, deterministic keys and time, fixture worlds, Nostr-specific failure modes. - [Pattern · Publishing an nsite (NIP-5A)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md): Kind 15128/35128/5128, manifest tags, aggregate hash, gateway resolution, Blossom content-type measurements, identity rule, definition of done. - [Pattern · Publishing an Android app to Zapstore](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/zapstore-publishing.md): The zsp CLI, NIP-82 event triplet 32267/30063/3063, cert linking, local sandbox first, gotchas. - [Pattern · GRASP repo as structural layer](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/grasp-as-structural-layer.md): Use a NIP-34/GRASP git repo as the structure for any curated collection; federation via submodules. - [Pattern · Going public](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/going-public.md): Mirror locally built events, Blossom blobs, GRASP repos and nsites to public infrastructure. - [Pattern · OpenTimestamps Merkle extension](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/merkle-ots-extension.md): Stamp once over a Merkle root and derive per-leaf OTS proofs that verify with stock `ots verify`. ## Primary sources - [Source · NIP-01 (full text)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nip-01.md): The basic protocol: event structure, serialization, kinds, client/relay messages. Vendored, MIT. - [Source · NIPs kind registry](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md): The kind table and message types from the NIPs README (vendored). Check here before allocating a kind. - [Source · The outbox model (NIP-65)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/outbox-model.md): Outbox/inbox mechanics, routing rules, and what outbox does not solve. - [Source · Blossom](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md): Content-addressed blob storage (BUDs), server behaviour measurements, usage. - [Source · Zapstore / NIP-82](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/zapstore.md): App distribution on Nostr: the 32267/30063/3063 schema, the zsp CLI, cert linking, whitelisting. - [Source · FIPS](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fips.md): Mesh routing with Nostr keypairs as node identity; discovery and NAT traversal over relays. - [Source · fiatjaf: a vision for content discovery](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fiatjaf-vision.md): fiatjaf's essay on relay usage and content discovery, summarised with link. - [Source · Hodlbod: Building Nostr](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/hodlbod-book.md): Pointer to and summary of the book Building Nostr. - [Source · nostrdesign.org principles](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nostr-design-principles.md): The Nostr Design guiding principles, summarised. - [Source · OpenSats: advancements in Nostr clients](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/opensats-advancements.md): The OpenSats client report, summary and quotes. - [Source · Nostr Rising podcast](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nostr-rising.md): Episodes and themes of the Nostr Rising series. - [Source · Videos and podcasts](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/videos.md): Pointers to talks by fiatjaf, Hodlbod, Pablo, Dilger and others. ## Optional: Voices - [Voice · fiatjaf (distillation)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md): The creator's positions: relay-centric, anti-super-peer, censorship-resistance as emergent client behaviour. - [Voice · fiatjaf: essays (annotated)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/essays.md): Annotated bibliography of fiatjaf's web essays. - [Voice · fiatjaf: on-Nostr publications](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/on-nostr.md): His long-form articles and sampled notes from his relays. - [Voice · No Solutions podcast (distillation)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/README.md): Gigi & Pablo Fernandez: no-global, rug-pull resistance, trade-offs out loud, the local relay, Nostr as AI substrate. - [Voice · No Solutions: episodes](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/episodes.md): Full episode table and transcript notes. - [Voice · Constant (distillation)](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/constant/README.md): Teach the paradigm, relays for curation, identity is not the key, TEPP, OpenTimestamps, the subjective web. ## Optional: Code examples - [Example · ping-relay.ts](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/ping-relay.md): Connect to a relay with nostr-tools and read a few kind 1 events. - [Example · fetch-profile.ts](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/fetch-profile.md): Fetch a kind 0 profile. - [Example · fetch-grasp-repo.ts](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/fetch-grasp-repo.md): Fetch a NIP-34 repository announcement from a GRASP relay. - [Example · blossom-upload.ts](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/blossom-upload.md): Upload a blob to a Blossom server with a signed kind 24242 auth event. - [Example · publish-wrap-with-auth.ts](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/publish-wrap-with-auth.md): Publish a pre-signed event to a relay that demands NIP-42 AUTH, without re-signing it.