Relay List Metadata

1 Overview

Nostr has no central directory. A client cannot know which relays hold a user's events. This NIP solves that problem. Each user publishes one relay list event of kind:10002. The list names the relays where the user generally writes events. It also names the relays where the user generally reads mentions.

Other clients read this list and route traffic with it. To fetch a user's events, a client goes to that user's write relays. To notify a user, a client delivers the event to that user's read relays. This routing scheme is often called the outbox model.

Kind 10002 sits in the replaceable range of NIP-01. A relay keeps only the latest relay list per pubkey. Publishing a new list replaces the old one everywhere it lands.

2 The Relay List Event

The relay list is a replaceable event with kind:10002. The event must include a list of r tags. Each r tag carries one relay URL as its value. A tag may add an optional marker: read or write. If the marker is omitted, the relay is both read and write.

{
  "kind": 10002,
  "tags": [
    ["r", "wss://alicerelay.example.com"],
    ["r", "wss://brando-relay.com"],
    ["r", "wss://expensive-relay.example2.com", "write"],
    ["r", "wss://nostr-relay.example.com", "read"]
  ],
  "content": "",
  // other fields per NIP-01: id, pubkey, created_at, sig
}

3 Reading Rules

The two markers split a user's traffic into two directions. Clients follow two rules when they fetch events:

• When a client downloads events from a user, it should use the write relays of that user. The author's own events live there.
• When a client downloads events about a user — events where the user is tagged (mentioned) — it should use that user's read relays. Other people deliver mentions there.

4 Publishing Rules

When a client publishes an event, it should deliver the event along three routes:

1. Send the event to the write relays of the author.
2. Send the event to all read relays of each tagged user.
3. Send the author's own kind:10002 event to all relays the event was published to.

Rule 3 re-publishes the relay list alongside every event. Any relay that holds one of your events then also holds your current address label. Readers who find the event can find the rest of your work.

5 Size and Discoverability

Size. Clients should guide users to keep kind:10002 lists small: 2 to 4 relays of each category. A short list keeps the outbox model cheap. Readers open few connections. Writers send few copies.

Discoverability. Clients should spread an author's kind:10002 event to as many relays as viable. Pay attention to relays that serve, at any moment, as well-known public indexers for these relay lists. These are the relays where most other clients and users connect to publish and fetch relay lists. The list itself must be easy to find, or the routing rules above cannot start.

6 Worked Example

Alice runs two general relays, one paid write-only relay, and one inbox relay. Her full relay list event:

{
  "id": "7fa31c1bb9…d02e44",
  "pubkey": "a1ec9e9a41…33cf01",
  "created_at": 1749762600,
  "kind": 10002,
  "tags": [
    ["r", "wss://alicerelay.example.com"],
    ["r", "wss://brando-relay.com"],
    ["r", "wss://expensive-relay.example2.com", "write"],
    ["r", "wss://nostr-relay.example.com", "read"]
  ],
  "content": "",
  "sig": "c9e02b1157…88ab90"
}

Bob wants Alice's notes. His client first pulls her relay list from an indexer relay. It reads the markers, then queries her write relays. Orange lines go to a relay. Blue lines come back.

-- step 1: wss://indexer.example.net - find Alice's relay list --
→ ["REQ", "rl", {"kinds":[10002], "authors":["a1ec9e9a41…"]}]
← ["EVENT", "rl", {"kind":10002, "tags":[["r","wss://alicerelay.example.com"], …]}]
← ["EOSE", "rl"]
→ ["CLOSE", "rl"]

-- step 2: wss://alicerelay.example.com - a write relay - fetch her notes --
→ ["REQ", "feed", {"kinds":[1], "authors":["a1ec9e9a41…"], "limit":20}]
← ["EVENT", "feed", {"id":"41b2c9d0aa…", "kind":1, "content":"gm", …}]
← ["EOSE", "feed"]

-- step 3: Bob replies and tags Alice - deliver to her read relay --
-- on wss://nostr-relay.example.com (Alice reads mentions here) --
→ ["EVENT", {"kind":1, "tags":[["p","a1ec9e9a41…"]], "content":"gm back", …}]
← ["OK", "8c00f1e2bd…", true, ""]
→ ["EVENT", {"kind":10002, "tags":[["r","wss://bobrelay.example.org"], …], …}]
← ["OK", "5d2e97ac10…", true, ""]

Note step 3. Bob sends his own kind:10002 right after the reply. Alice's client can now route her answer straight to Bob's read relays.

7 Version History

NIP-65 began life as "Feed Advertisements" and shrank over time into a tight routing spec. Notable changes, newest first:

• 20252025-04Added publishing rule 3: re-publish the author's kind:10002 to every relay the event was sent to.
• 20252025-04The whole spec was shrunk and rewritten for clarity. URI-normalization details and long rationale text were dropped.
• 20242024Typo fixes, JSON formatting, and links to outbox-model articles (links removed again in the 2025 rewrite).
• 20232023-10Defined the terms read relay and write relay precisely; required normalized relay URIs with trailing slashes trimmed.
• 20232023-08Vitor Pamplona simplified the spec into the read/write marker form used today.
• 20232023-02Read relays were recognized as their own category, and the NIP was renamed toward Relay List Metadata.
• Origin2023-02-03Mike Dilger proposed the NIP as "Feed Advertisements".

8 See Also

• NIP-01 — the base event format, the replaceable-event rules for kind 10002, and the p tag used to detect mentions.
• NIP-02 — the follow list; pair it with relay lists to build a full outbox-model feed.
• NIP-17 — private direct messages use a separate inbox relay list (kind:10050), not this one.
• NIP-66 — relay liveness monitoring; helps pick relays that are worth listing.
• NIP-11 — the relay information document for the relays you list here.