NIP-11: How Nostr Relays Advertise What They Can Do

Nostr is often introduced as “notes and other stuff transmitted by relays.” That slogan is accurate and incomplete. Clients speak a small event protocol; relays decide what they store, forward, rate-limit, and refuse. Users experience those decisions as mysterious disconnects, silent drops, or sudden paywalls — unless the relay explains itself.

NIP-11 is that explanation format: a Relay Information Document. It is optional, self-reported JSON metadata served over HTTP from the same URI as the relay’s WebSocket. This note is protocol literacy — how to read what relays claim — not a recruitment pitch to “join Nostr now.”

What NIP-11 is for

The official NIP text (living draft, optional, relay-scoped) says relays may provide server metadata so clients learn capabilities, administrative contacts, and server attributes; secondary mirrors and blog summaries can lag or trim fields, so prefer the canonical nips repository on GitHub when details matter. Discovery beats folklore: instead of guessing whether a relay supports deletions, auth, or paid writes, a client can fetch a document and adapt UI and connection strategy.

Mechanically, a client issues an HTTP(S) request to the relay URL with:

Accept: application/nostr+json

The relay SHOULD return JSON. Relays MUST send CORS headers so browser clients can read the document. Any field may be omitted; clients MUST ignore unknown fields — which keeps the protocol extensible without breaking old software.

Core fields you will actually see

A typical document can include:

• name / description — human labels for relay lists and settings screens. Names are encouraged to stay short; descriptions are plain text.
• banner / icon — optional imagery so non-technical users can recognise a relay the way they recognise a site, not only a wss:// string.
• pubkey — an administrative contact key (32-byte hex). Intended uses include reporting abuse or asking for technical help via encrypted DMs (see related NIPs). Operators are not obliged to reply.
• self — optional relay identity distinct from the admin key, so the relay can publish events as itself.
• contact — alternate URI contact (mailto:, https:, etc.). The NIP prefers Nostr DM via pubkey when possible.
• supported_nips — array of integer NIP numbers the relay implements (for example 1 for NIP-01, 9 for NIP-09). Client-only NIPs SHOULD NOT be advertised.
• software / version — optional implementation URL and version string for debugging and trust assessment.
• terms_of_service — optional link to policy text.

These fields are how a client answers: Who runs this? What features might work? Where do I send abuse reports?

The limitation object — where UX meets policy

Extra fields matter as much as the friendly name. NIP-11 documents a limitation object describing practical constraints. Clients should expect requests beyond these limits to fail or be rejected.

Common keys include:

Signal	Why users care
max_message_length / max_content_length	Huge notes or nested JSON get cut off
max_subscriptions / max_limit	Feeds stall or truncate under heavy filters
min_pow_difficulty	Writes need proof-of-work (NIP-13)
auth_required	NIP-42 auth before other actions
payment_required	Pay before the relay will act
restricted_writes	Writes gated by whitelist, niche kinds, or similar known policy
created_at_*_limit	Out-of-range timestamps rejected

There is also optional pay-to-relay metadata (payments_url, fees with admission, subscription, or per-publication schedules). That is operational signalling — how the relay funds itself — not an invitation to speculate on anything.

Important: NIP-11 is self-reported. A relay can claim supported_nips: […everything…] and still behave differently. Good clients treat the document as a hint for discovery and UX, then verify behaviour in live traffic.

Why advertising capabilities helps users choose relays

Without NIP-11, relay choice is social rumour: “this one is fast,” “that one censors,” “the other one is paid.” With NIP-11, a client can:

1. Filter for features — only show relays advertising NIP-42 if the user needs auth-gated inboxes; prefer relays listing NIP-09 if deletion support matters.
2. Surface limits early — warn that max_subscriptions is low before the user opens twenty filters and blames the client.
3. Explain moderation posture — restricted_writes, terms links, and admin pubkey do not equal a full content policy, but they tell you the relay is not claiming to be a lawless free-for-all.
4. Route sensibly — read-heavy public relays vs write-gated community relays can be labelled instead of silently failing.
5. Support accountability — a published contact path for illegal-content or abuse reports is basic hygiene for operators who want to keep the network usable.

In South Africa and elsewhere on uneven networks, knowing a relay needs payment or PoW before burning mobile data on a doomed publish is not a luxury — it is protocol UX.

Moderation and limits without the culture war framing

Every relay is a server with a disk and a legal residence. “Decentralised” means many policies, not zero policies. NIP-11 does not invent moderation; it makes some constraints machine-readable.

Reading auth_required, payment_required, and restricted_writes together sketches an access model: open read/write, member-only write, spam-priced write, or specialty relay. Pair that with a terms URL when present. Then decide whether that model matches your use — personal broadcasting, community chat, long-form, or private circles.

What NIP-11 does not give you: cryptographic proof of honest storage, global censorship resistance from a single relay, or a substitute for verifying signatures on events. Nostr’s security model still centres on signed events and multi-relay publication. Relay metadata is the map; it is not the territory.

How to fetch one yourself (for literacy, not onboarding)

Conceptually:

curl -H "Accept: application/nostr+json" https://relay.example.com

(Use the HTTPS form of a wss:// relay URL.) Pretty-print the JSON and look for supported_nips, limitation, and contact fields. Compare two relays side by side. Notice what is missing as much as what is present — omitted fields are allowed.

Clients automate this on add-relay flows. Understanding the document means you can tell whether a client is showing you protocol data or inventing marketing copy.

Takeaways

• NIP-11 is the living, optional standard way Nostr relays publish capabilities, contacts, and limits (watch for mirror drift vs master).
• Clients use it to choose relays, adapt features, and explain failures.
• Documents are advisory; verify behaviour.
• Limits and payment flags are part of moderation and sustainability signalling, not footnotes.
• Protocol literacy beats vibe-based relay lists — especially when bandwidth and trust are scarce.

What this note deliberately does not do

It does not tell you which relays to join, sell NIP-05 names, or operate a relay product. It does not treat pay-to-relay fees as an investment opportunity. It is not a client onboarding guide or a zap/trading tutorial — only literacy for reading self-reported relay metadata, with the caveat that documents can lag mirrors and behaviour can diverge from claims.

Related on CryptoDecentral

• Nostr pillar
• Network metrics

Further reading (primary)

• NIP-11 on GitHub (canonical)
• Nostr NIPs repository