12<html lang="en">3<head>4<meta charset="utf-8">5<meta name="viewport" content="width=device-width, initial-scale=1">6<title>NIP-65 - Relay List Metadata — Nostr Instruction Manual</title>7<meta name="description" content="NIP-65: relay list metadata. The kind 10002 event that advertises a user's read and write relays, and the outbox routing rules built on it.">8<link rel="preload" href="../assets/fonts/michroma-400-latin.woff2" as="font" type="font/woff2" crossorigin>9<link rel="preload" href="../assets/fonts/exo2-var-latin.woff2" as="font" type="font/woff2" crossorigin>10<link rel="preload" href="../assets/fonts/sairacondensed-600-latin.woff2" as="font" type="font/woff2" crossorigin>11<link rel="preload" href="../assets/fonts/sairacondensed-700-latin.woff2" as="font" type="font/woff2" crossorigin>12<link rel="preload" href="../assets/fonts/sairacondensed-500-latin.woff2" as="font" type="font/woff2" crossorigin>13<link rel="preload" href="../assets/fonts/sharetechmono-400-latin.woff2" as="font" type="font/woff2" crossorigin>14<link rel="preload" href="../assets/fonts/exo2-400i-latin.woff2" as="font" type="font/woff2" crossorigin>15<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">16<link rel="stylesheet" href="../assets/manual.css">17</head>18<body>1920<svg width="0" height="0" style="position:absolute">21 <defs>22 <marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">23 <path d="M1,1 L8,4.5 L1,8 Z" fill="#f26a00"/>24 </marker>25 <marker id="arrb" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">26 <path d="M1,1 L8,4.5 L1,8 Z" fill="#2e5f9e"/>27 </marker>28 </defs>29</svg>3031<div class="page">32 <span class="staple s1"></span><span class="staple s2"></span>3334 <header class="band">35 <a class="logo" href="../index.html">NOSTR<b>▸</b>PROTOCOL MANUAL</a>36 <span class="booklet-note">Chapter 65 - Relay Ops</span>37 </header>38 <nav class="tabs">39 <a href="../index.html">Contents</a>40 <a href="#overview" class="on">Overview</a>41 <a href="#spec">Spec</a>42 <a href="#examples">Examples</a>43 <a href="#history">History</a>44 </nav>4546 <div class="chapter">47 <div class="nipno" data-n="65">65</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 65</div>50 <h1>Relay List Metadata</h1>51 <p class="sub">A small replaceable event that tells the network where a user writes and where a user reads mentions.</p>52 </div>53 </div>5455 <main class="spread">56 <div class="main">5758 <h2 class="bar" id="overview"><span class="num">1</span> Overview</h2>59 <p>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 <strong>relay list</strong> event of <code>kind:10002</code>. The list names the relays where the user generally <strong>writes</strong> events. It also names the relays where the user generally <strong>reads</strong> mentions.</p>60 <p>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 <strong>outbox model</strong>.</p>61 <p>Kind <code>10002</code> sits in the replaceable range of <a href="01.html">NIP-01</a>. A relay keeps only the latest relay list per pubkey. Publishing a new list replaces the old one everywhere it lands.</p>6263 <div class="box hint">64 <span class="tag">Hint!</span>65 <p>Think of the relay list as the address label on the back of a game cartridge. It does not hold the game. It only tells the mail carrier where deliveries go and where fan mail arrives.</p>66 </div>6768 <figure class="diagram">69 <div class="frame">70 <svg viewBox="0 0 560 224" role="img" aria-label="Alice writes to her write relays and reads mentions from her read relays; Bob fetches from her write relays; Carol mentions her on her read relays">71 <rect class="d-actor" x="10" y="88" width="100" height="50" rx="8"/>72 <text class="d-actor-label" x="60" y="117" text-anchor="middle">Alice</text>73 <rect class="d-actor" x="225" y="22" width="120" height="44" rx="8"/>74 <text class="d-actor-label" x="285" y="42" text-anchor="middle">Write relays</text>75 <text class="d-note" x="285" y="58" text-anchor="middle">Alice's outbox</text>76 <rect class="d-actor" x="225" y="158" width="120" height="44" rx="8"/>77 <text class="d-actor-label" x="285" y="178" text-anchor="middle">Read relays</text>78 <text class="d-note" x="285" y="194" text-anchor="middle">Alice's inbox</text>79 <rect class="d-actor" x="445" y="22" width="105" height="44" rx="8"/>80 <text class="d-actor-label" x="497" y="49" text-anchor="middle">Bob</text>81 <rect class="d-actor" x="445" y="158" width="105" height="44" rx="8"/>82 <text class="d-actor-label" x="497" y="185" text-anchor="middle">Carol</text>83 <path class="d-msg d-flow" d="M112,100 C160,84 180,58 222,48"/>84 <text class="d-label" x="150" y="60" text-anchor="middle">EVENT</text>85 <path class="d-msg blue d-flow" d="M443,44 L348,44"/>86 <text class="d-label" x="396" y="36" text-anchor="middle">REQ</text>87 <path class="d-msg d-flow" d="M443,180 L348,180"/>88 <text class="d-label" x="396" y="172" text-anchor="middle">mention</text>89 <path class="d-msg blue d-flow" d="M222,178 C180,168 160,142 112,126"/>90 <text class="d-label" x="150" y="166" text-anchor="middle">REQ #p</text>91 <circle r="4" fill="#f26a00">92 <animateMotion dur="2.6s" repeatCount="indefinite" path="M112,100 C160,84 180,58 222,48"/>93 </circle>94 <circle r="4" fill="#2e5f9e">95 <animateMotion dur="2.6s" begin="1.3s" repeatCount="indefinite" path="M222,178 C180,168 160,142 112,126"/>96 </circle>97 </svg>98 </div>99 <figcaption>Fig. 65-1 — <b>The outbox model.</b> Alice publishes to her write relays. Bob fetches her events there. Carol delivers a mention to Alice's read relays, and Alice picks it up.</figcaption>100 </figure>101102 <h2 class="bar" id="spec"><span class="num">2</span> The Relay List Event</h2>103 <p>The relay list is a replaceable event with <code>kind:10002</code>. The event must include a list of <code>r</code> tags. Each <code>r</code> tag carries one relay URL as its value. A tag may add an optional marker: <code>read</code> or <code>write</code>. If the marker is omitted, the relay is both <strong>read</strong> and <strong>write</strong>.</p>104105 <div class="crt">106 <div class="titlebar">Wire format - kind 10002 relay list</div>107<pre>{108 <span class="k">"kind"</span>: 10002,109 <span class="k">"tags"</span>: [110 [<span class="s">"r"</span>, <span class="s">"wss://alicerelay.example.com"</span>],111 [<span class="s">"r"</span>, <span class="s">"wss://brando-relay.com"</span>],112 [<span class="s">"r"</span>, <span class="s">"wss://expensive-relay.example2.com"</span>, <span class="s">"write"</span>],113 [<span class="s">"r"</span>, <span class="s">"wss://nostr-relay.example.com"</span>, <span class="s">"read"</span>]114 ],115 <span class="k">"content"</span>: <span class="s">""</span>,116 <span class="c">// other fields per NIP-01: id, pubkey, created_at, sig</span>117}</pre>118 </div>119120 <div class="tscroll"><table class="ref">121 <caption>The r tag</caption>122 <tr><th>Position</th><th>Value</th><th>Rule</th></tr>123 <tr><td class="btn">r</td><td>tag name</td><td>Marks one relay entry. The event must include a list of these tags.</td></tr>124 <tr><td><span class="kbd">value</span></td><td>relay URL</td><td>The WebSocket URL of the relay, for example <code>wss://relay.example.com</code>.</td></tr>125 <tr><td><span class="kbd">marker</span></td><td><code>read</code> or <code>write</code></td><td>Optional. <code>write</code>: the user publishes here. <code>read</code>: the user checks mentions here. Omitted: the relay serves both roles.</td></tr>126 </table></div>127128 <div class="box tech">129 <span class="tag">Tech Note</span>130 <p>The source spec shows <code>content</code> as an empty string but states no rule for it. Treat <code>content</code> as unused. Do not put relay data there. Also note: the source's code block is labeled YAML yet holds JSON with a comment. The wire format is the plain <a href="01.html">NIP-01</a> JSON event.</p>131 </div>132133 <h2 class="bar" id="reading"><span class="num">3</span> Reading Rules</h2>134 <p>The two markers split a user's traffic into two directions. Clients follow two rules when they fetch events:</p>135 <ul>136 <li>When a client downloads events <strong>from</strong> a user, it should use the <strong>write</strong> relays of that user. The author's own events live there.</li>137 <li>When a client downloads events <strong>about</strong> a user — events where the user is tagged (mentioned) — it should use that user's <strong>read</strong> relays. Other people deliver mentions there.</li>138 </ul>139 <div class="box warn">140 <span class="tag">Warning!</span>141 <p>The markers describe the list owner's habits, not the reader's. A relay marked <code>read</code> is where the owner reads. To reach the owner, you <em>write</em> to their read relays. Swapping the two directions is the classic NIP-65 bug.</p>142 </div>143144 <h2 class="bar" id="publishing"><span class="num">4</span> Publishing Rules</h2>145 <p>When a client publishes an event, it should deliver the event along three routes:</p>146 <ol>147 <li>Send the event to the <strong>write</strong> relays of the author.</li>148 <li>Send the event to all <strong>read</strong> relays of each tagged user.</li>149 <li>Send the author's own <code>kind:10002</code> event to all relays the event was published to.</li>150 </ol>151 <p>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.</p>152153 <figure class="diagram">154 <div class="frame">155 <svg viewBox="0 0 560 250" role="img" aria-label="Sequence diagram: Alice's client sends the note and her relay list to her write relay and to Bob's read relay">156 <line class="d-wire" x1="95" y1="42" x2="95" y2="235" stroke-dasharray="3 4"/>157 <line class="d-wire" x1="300" y1="42" x2="300" y2="235" stroke-dasharray="3 4"/>158 <line class="d-wire" x1="490" y1="42" x2="490" y2="235" stroke-dasharray="3 4"/>159 <rect class="d-actor" x="35" y="8" width="120" height="32" rx="6"/>160 <text class="d-actor-label" x="95" y="29" text-anchor="middle">Alice's client</text>161 <rect class="d-actor" x="235" y="8" width="130" height="32" rx="6"/>162 <text class="d-actor-label" x="300" y="29" text-anchor="middle">Alice write relay</text>163 <rect class="d-actor" x="425" y="8" width="130" height="32" rx="6"/>164 <text class="d-actor-label" x="490" y="29" text-anchor="middle">Bob read relay</text>165 <path class="d-msg" d="M95,70 L295,70"/>166 <text class="d-label" x="195" y="63" text-anchor="middle">["EVENT", kind 1, #p Bob]</text>167 <path class="d-msg" d="M95,105 L485,105"/>168 <text class="d-label" x="290" y="98" text-anchor="middle">["EVENT", kind 1, #p Bob]</text>169 <path class="d-msg" d="M95,140 L295,140"/>170 <text class="d-label" x="195" y="133" text-anchor="middle">["EVENT", kind 10002]</text>171 <path class="d-msg" d="M95,175 L485,175"/>172 <text class="d-label" x="290" y="168" text-anchor="middle">["EVENT", kind 10002]</text>173 <text class="d-note" x="290" y="215" text-anchor="middle">The note reaches the author's outbox and every tagged user's inbox.</text>174 <text class="d-note" x="290" y="230" text-anchor="middle">The relay list rides along to every relay that got the note.</text>175 </svg>176 </div>177 <figcaption>Fig. 65-2 — <b>Publishing a mention.</b> Alice's client sends the note to her write relay and to Bob's read relay, then re-publishes her <code>kind:10002</code> to both.</figcaption>178 </figure>179180 <h2 class="bar" id="size"><span class="num">5</span> Size and Discoverability</h2>181 <p><strong>Size.</strong> Clients should guide users to keep <code>kind:10002</code> 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.</p>182 <p><strong>Discoverability.</strong> Clients should spread an author's <code>kind:10002</code> 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.</p>183 <div class="box hint">184 <span class="tag">Hint!</span>185 <p>Small list, wide broadcast. Keep the relay list tight, but scatter the event itself far and wide. The list is tiny, so copies are cheap.</p>186 </div>187188 <h2 class="bar" id="examples"><span class="num">6</span> Worked Example</h2>189 <p>Alice runs two general relays, one paid write-only relay, and one inbox relay. Her full relay list event:</p>190 <div class="crt">191 <div class="titlebar">Alice's relay list - kind 10002</div>192<pre>{193 <span class="k">"id"</span>: <span class="s">"7fa31c1bb9…d02e44"</span>,194 <span class="k">"pubkey"</span>: <span class="s">"a1ec9e9a41…33cf01"</span>,195 <span class="k">"created_at"</span>: 1749762600,196 <span class="k">"kind"</span>: 10002,197 <span class="k">"tags"</span>: [198 [<span class="s">"r"</span>, <span class="s">"wss://alicerelay.example.com"</span>],199 [<span class="s">"r"</span>, <span class="s">"wss://brando-relay.com"</span>],200 [<span class="s">"r"</span>, <span class="s">"wss://expensive-relay.example2.com"</span>, <span class="s">"write"</span>],201 [<span class="s">"r"</span>, <span class="s">"wss://nostr-relay.example.com"</span>, <span class="s">"read"</span>]202 ],203 <span class="k">"content"</span>: <span class="s">""</span>,204 <span class="k">"sig"</span>: <span class="s">"c9e02b1157…88ab90"</span>205}</pre>206 </div>207 <p>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.</p>208 <div class="crt">209 <div class="titlebar">Session transcript - the outbox model in action</div>210<pre><span class="c">-- step 1: wss://indexer.example.net - find Alice's relay list --</span>211<span class="send">→ ["REQ", "rl", {"kinds":[10002], "authors":["a1ec9e9a41…"]}]</span>212<span class="recv">← ["EVENT", "rl", {"kind":10002, "tags":[["r","wss://alicerelay.example.com"], …]}]</span>213<span class="recv">← ["EOSE", "rl"]</span>214<span class="send">→ ["CLOSE", "rl"]</span>215216<span class="c">-- step 2: wss://alicerelay.example.com - a write relay - fetch her notes --</span>217<span class="send">→ ["REQ", "feed", {"kinds":[1], "authors":["a1ec9e9a41…"], "limit":20}]</span>218<span class="recv">← ["EVENT", "feed", {"id":"41b2c9d0aa…", "kind":1, "content":"gm", …}]</span>219<span class="recv">← ["EOSE", "feed"]</span>220221<span class="c">-- step 3: Bob replies and tags Alice - deliver to her read relay --</span>222<span class="c">-- on wss://nostr-relay.example.com (Alice reads mentions here) --</span>223<span class="send">→ ["EVENT", {"kind":1, "tags":[["p","a1ec9e9a41…"]], "content":"gm back", …}]</span>224<span class="recv">← ["OK", "8c00f1e2bd…", true, ""]</span>225<span class="send">→ ["EVENT", {"kind":10002, "tags":[["r","wss://bobrelay.example.org"], …], …}]</span>226<span class="recv">← ["OK", "5d2e97ac10…", true, ""]</span></pre>227 </div>228 <p>Note step 3. Bob sends his own <code>kind:10002</code> right after the reply. Alice's client can now route her answer straight to Bob's read relays.</p>229230 <h2 class="bar" id="history"><span class="num">7</span> Version History</h2>231 <p>NIP-65 began life as "Feed Advertisements" and shrank over time into a tight routing spec. Notable changes, newest first:</p>232 <ul class="patchnotes">233 <li><span class="ver">2025</span><span class="when">2025-04</span>Added publishing rule 3: re-publish the author's <code>kind:10002</code> to every relay the event was sent to.</li>234 <li><span class="ver">2025</span><span class="when">2025-04</span>The whole spec was shrunk and rewritten for clarity. URI-normalization details and long rationale text were dropped.</li>235 <li class="minor"><span class="ver">2024</span><span class="when">2024</span>Typo fixes, JSON formatting, and links to outbox-model articles (links removed again in the 2025 rewrite).</li>236 <li><span class="ver">2023</span><span class="when">2023-10</span>Defined the terms read relay and write relay precisely; required normalized relay URIs with trailing slashes trimmed.</li>237 <li><span class="ver">2023</span><span class="when">2023-08</span>Vitor Pamplona simplified the spec into the read/write marker form used today.</li>238 <li><span class="ver">2023</span><span class="when">2023-02</span>Read relays were recognized as their own category, and the NIP was renamed toward Relay List Metadata.</li>239 <li><span class="ver">Origin</span><span class="when">2023-02-03</span>Mike Dilger proposed the NIP as "Feed Advertisements".</li>240 </ul>241242 <div class="credits">243 <h3 class="cardhead">Original Proposal - Credits</h3>244 <table>245 <tr><td>Author</td><td>Mike Dilger</td></tr>246 <tr><td>First commit</td><td>2023-02-03 — “NIP-65 Feed Advertisements”</td></tr>247 <tr><td>Status</td><td>draft - optional — recommended for clients that follow the outbox model</td></tr>248 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/65.md">65.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/65.md">full change history</a></td></tr>249 </table>250 </div>251252 <h2 class="bar"><span class="num">8</span> See Also</h2>253 <ul>254 <li><a href="01.html">NIP-01</a> — the base event format, the replaceable-event rules for kind 10002, and the <code>p</code> tag used to detect mentions.</li>255 <li><a href="02.html">NIP-02</a> — the follow list; pair it with relay lists to build a full outbox-model feed.</li>256 <li><a href="17.html">NIP-17</a> — private direct messages use a separate inbox relay list (<code>kind:10050</code>), not this one.</li>257 <li><a href="66.html">NIP-66</a> — relay liveness monitoring; helps pick relays that are worth listing.</li>258 <li><a href="11.html">NIP-11</a> — the relay information document for the relays you list here.</li>259 </ul>260 </div>261262 <aside>263 <div class="cartridge">264 <div class="inner">265 <h3 class="cardhead">Spec Card</h3>266 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>267 <dl>268 <dt>Status</dt><dd><span class="chip draft">draft</span><span class="chip optional">optional</span></dd>269 <dt>Defines</dt><dd>kind 10002 - <code>r</code> tag with read/write markers</dd>270 <dt>Kind(s)</dt><dd>10002 (replaceable)</dd>271 <dt>Requires</dt><dd><a href="01.html">NIP-01</a></dd>272 <dt>Transport</dt><dd>WebSocket - JSON arrays</dd>273 <dt>First commit</dt><dd>2023-02-03</dd>274 <dt>Last updated</dt><dd>2026-06-13</dd>275 </dl>276 </div>277 </div>278 </aside>279 </main>280281 <nav class="navbtns">282 <a href="64.html">◀ NIP-64: Chess (Portable Game Notation)</a>283 <a href="66.html">NIP-66: Relay Liveness Monitoring ▶</a>284 </nav>285286 <footer class="pagefoot">287 <a href="../index.html">Nostr Protocol Manual</a>288 <span class="pageno">NIP 65 / F4</span>289 </footer>290</div>291292<script src="../assets/webmcp.js" defer></script>293</body>294</html>