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-10 - Text Notes and Threads — Nostr Instruction Manual</title>7<meta name="description" content="NIP-10: kind:1 text notes, marked e-tag reply threading (root/reply), q tags for quoting, p-tag notification, and the deprecated positional e-tag scheme.">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 10 - Social</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="10">10</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 10</div>50 <h1>Text Notes and Threads</h1>51 <p class="sub">How a kind:1 note replies to another note, how clients rebuild a thread from e, p, and q tags, and the older positional scheme kept only for backward compatibility.</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>NIP-10 defines <code>kind:1</code>, the plain text note. It is the most common event kind on Nostr. A user writes a short message; the client wraps it in an event and publishes it, following the rules of <a href="01.html">NIP-01</a>.</p>60 <p>A text note can stand alone, or it can reply to another text note. This NIP defines how a reply points back to the note it answers, and how a client walks a chain of replies to rebuild a thread. It also defines how a note can cite, or quote, another event without turning that citation into a reply.</p>61 <p>Two tagging schemes exist for replies. The <strong>marked e-tag scheme</strong> is preferred. It labels each <code>e</code> tag with a marker, so a client always knows which tag is the thread root and which is the direct parent. An older <strong>positional scheme</strong> relies only on tag order. It is deprecated, but old events still use it, so every client must still be able to read it.</p>6263 <div class="box hint">64 <span class="tag">Hint!</span>65 <p>This chapter builds on <a href="01.html">NIP-01</a>. Read that chapter first for the event object, the <code>e</code>/<code>p</code>/<code>a</code> tags, and how relays store and filter events.</p>66 </div>6768 <h2 class="bar" id="spec"><span class="num">2</span> Kind 1 - The Text Note</h2>69 <p>A <code>kind:1</code> event is a simple text note. The <code>content</code> field holds human-readable text. Clients SHOULD NOT put markup languages such as Markdown or HTML in <code>content</code>. A client renders <code>content</code> as plain text.</p>70 <p>An event references other events and users through three tags:</p>71 <div class="tscroll"><table class="ref">72 <caption>Tags used by kind:1 notes</caption>73 <tr><th>Tag</th><th>Purpose</th></tr>74 <tr><td class="btn">e</td><td>Points to another event. Marks the note as a reply, or a mention within the reply chain. See §3.</td></tr>75 <tr><td class="btn">q</td><td>Cites an event or an addressable-event coordinate that the <code>content</code> quotes. See §4.</td></tr>76 <tr><td class="btn">p</td><td>Lists the pubkeys involved in the thread, so they are notified. See §5.</td></tr>77 </table></div>78 <p>The author of any event referenced by an <code>e</code> or <code>q</code> tag SHOULD also be added as a <code>p</code> tag. This notifies that author of the new reply or quote.</p>7980 <h2 class="bar" id="marked-e"><span class="num">3</span> Marked "e" Tags (Preferred)</h2>81 <p>A <code>kind:1</code> event with an <code>e</code> tag is a reply to another <code>kind:1</code> event. Kind-1 replies MUST NOT be used to reply to any other kind. To reply to a different kind, use <a href="22.html">NIP-22</a> instead.</p>82 <div class="crt">83 <div class="titlebar">Wire format - marked e tag</div>84<pre>[<span class="s">"e"</span>, <span class="c"><event-id></span>, <span class="c"><relay-url></span>, <span class="c"><marker></span>, <span class="c"><pubkey></span>]</pre>85 </div>86 <div class="tscroll"><table class="ref">87 <caption>Marked e-tag elements</caption>88 <tr><th>Element</th><th>Required</th><th>Rule</th></tr>89 <tr><td class="btn">event-id</td><td>required</td><td>The id of the event being referenced.</td></tr>90 <tr><td class="btn">relay-url</td><td>optional</td><td>A recommended relay for the reference. Clients SHOULD supply a valid URL, but may leave it as an empty string <code>""</code>.</td></tr>91 <tr><td class="btn">marker</td><td>optional</td><td>One of <code>"reply"</code> or <code>"root"</code>.</td></tr>92 <tr><td class="btn">pubkey</td><td>optional</td><td>SHOULD be the pubkey of the author of the referenced event.</td></tr>93 </table></div>94 <p>An <code>e</code> tag marked <code>"root"</code> holds the id of the event at the root of the thread. An <code>e</code> tag marked <code>"reply"</code> holds the id of the event this note directly answers. A top-level reply, one that answers the root itself, uses only a single <code>"root"</code>-marked tag; it does not also add a <code>"reply"</code> tag for the same event. A direct reply to the root of a thread has exactly one marked <code>e</code> tag, of type <code>"root"</code>.</p>95 <p>Order the marked <code>e</code> tags by the reply stack, from the root to the direct parent. This scheme is preferred over the positional scheme because it lets an event mention other events without any risk of confusing a mention with the root id or the reply id.</p>96 <p>The <code>pubkey</code> element supports the outbox model: when a relay hint fails to resolve an event, a client can look for it on the referenced author's own write relays instead.</p>9798 <figure class="diagram">99 <div class="frame">100 <svg viewBox="0 0 560 300" role="img" aria-label="Thread tree: a root note has two top-level replies marked root; one of those replies has a nested reply marked root and reply">101 <rect class="d-actor" x="195" y="20" width="170" height="54" rx="8"/>102 <text class="d-actor-label" x="280" y="43" text-anchor="middle">Root Note R</text>103 <text class="d-note" x="280" y="61" text-anchor="middle">no e tags</text>104 <rect class="d-actor" x="30" y="150" width="180" height="54" rx="8"/>105 <text class="d-actor-label" x="120" y="173" text-anchor="middle">Reply A</text>106 <text class="d-note" x="120" y="191" text-anchor="middle">e: root -> R</text>107 <rect class="d-actor" x="350" y="150" width="180" height="54" rx="8"/>108 <text class="d-actor-label" x="440" y="173" text-anchor="middle">Reply C</text>109 <text class="d-note" x="440" y="191" text-anchor="middle">e: root -> R</text>110 <rect class="d-actor" x="20" y="240" width="230" height="54" rx="8"/>111 <text class="d-actor-label" x="135" y="263" text-anchor="middle">Reply B</text>112 <text class="d-note" x="135" y="281" text-anchor="middle">e: root -> R, reply -> A</text>113 <path class="d-msg" d="M240,74 C200,105 160,120 130,148"/>114 <path class="d-msg" d="M320,74 C370,105 410,120 435,148"/>115 <path class="d-msg" d="M110,204 C105,215 100,225 100,238"/>116 <text class="d-label" x="150" y="115" text-anchor="middle">root</text>117 <text class="d-label" x="410" y="115" text-anchor="middle">root</text>118 <text class="d-label" x="60" y="225" text-anchor="middle">reply</text>119 </svg>120 </div>121 <figcaption>Fig. 10-1 — <b>Thread structure.</b> Reply A and Reply C both answer the root directly, so each carries only a "root"-marked e tag. Reply B answers Reply A, so it carries both a "root" tag (pointing to R) and a "reply" tag (pointing to A).</figcaption>122 </figure>123124 <div class="box tech">125 <span class="tag">Tech Note</span>126 <p>The source spec never states how a client tells the marked scheme apart from the positional scheme below. In practice, clients check the fourth array element: if it is the string <code>"root"</code> or <code>"reply"</code>, the event uses the marked scheme. If the fourth element is absent, the event uses the positional scheme. This heuristic is universal in implementations but is not written down in the spec text itself.</p>127 </div>128129 <h2 class="bar" id="q-tag"><span class="num">4</span> Quoting with "q" Tags</h2>130 <p>A <code>q</code> tag MAY be used when the <code>content</code> of a note cites another event using a <code>nostr:</code> URI, as defined in <a href="21.html">NIP-21</a>. A citation is not a reply. It does not change the thread structure.</p>131 <div class="crt">132 <div class="titlebar">Wire format - q tag</div>133<pre>[<span class="s">"q"</span>, <span class="c"><event-id> or <event-address></span>, <span class="c"><relay-url></span>, <span class="c"><pubkey-if-a-regular-event></span>]</pre>134 </div>135 <div class="tscroll"><table class="ref">136 <caption>q-tag elements</caption>137 <tr><th>Element</th><th>Meaning</th></tr>138 <tr><td class="btn">event-id or event-address</td><td>The id of a regular event, or the <code>kind:pubkey:d-tag</code> coordinate of an addressable event, per <a href="01.html">NIP-01</a>.</td></tr>139 <tr><td class="btn">relay-url</td><td>A recommended relay for the cited event.</td></tr>140 <tr><td class="btn">pubkey</td><td>The author of the cited event, when it is a regular (non-addressable) event.</td></tr>141 </table></div>142 <p>The author of a <code>q</code>-tagged event SHOULD also be added as a <code>p</code> tag, to notify them that their note was quoted.</p>143144 <div class="box tech">145 <span class="tag">Tech Note</span>146 <p>Unlike the marked <code>e</code> tag, the source spec does not mark the <code>relay-url</code> or <code>pubkey</code> elements of the <code>q</code> tag as optional or required. This page treats them as recommended but not mandatory, matching the equivalent elements of the <code>e</code> tag, but the source text leaves this unstated.</p>147 </div>148149 <h2 class="bar" id="p-tag"><span class="num">5</span> The "p" Tag - Notifying Participants</h2>150 <p>A text note's <code>p</code> tags list the pubkeys involved in a reply thread. When a client builds a reply to a text event <var>E</var>, the reply's <code>p</code> tags SHOULD contain every <code>p</code> tag already on <var>E</var>, plus the <code>pubkey</code> of <var>E</var> itself. The order of these tags does not matter.</p>151 <p>Example: event <var>E</var> is authored by <code>a1</code> and carries <code>p</code> tags <code>[p1, p2, p3]</code>. A reply to <var>E</var> should carry <code>p</code> tags <code>[a1, p1, p2, p3]</code>, in any order.</p>152153 <figure class="diagram">154 <div class="frame">155 <svg viewBox="0 0 560 150" role="img" aria-label="p-tag propagation: event E authored by a1 with p tags p1, p2, p3 becomes a reply whose p tags are a1, p1, p2, p3">156 <rect class="d-actor" x="20" y="45" width="220" height="60" rx="8"/>157 <text class="d-actor-label" x="130" y="70" text-anchor="middle">Event E</text>158 <text class="d-note" x="130" y="88" text-anchor="middle">author a1 - p: p1, p2, p3</text>159 <rect class="d-actor" x="330" y="45" width="220" height="60" rx="8"/>160 <text class="d-actor-label" x="440" y="70" text-anchor="middle">Reply to E</text>161 <text class="d-note" x="440" y="88" text-anchor="middle">p: a1, p1, p2, p3</text>162 <path class="d-msg d-flow" d="M242,75 L328,75"/>163 <text class="d-label" x="285" y="60" text-anchor="middle">+ a1</text>164 <circle r="4" fill="#f26a00">165 <animateMotion dur="2.2s" repeatCount="indefinite" path="M242,75 L328,75"/>166 </circle>167 </svg>168 </div>169 <figcaption>Fig. 10-2 — <b>p-tag propagation.</b> The reply copies every p tag from the parent event, then adds the parent author's own pubkey.</figcaption>170 </figure>171172 <h2 class="bar" id="positional"><span class="num">6</span> Deprecated Positional "e" Tags</h2>173 <div class="box warn">174 <span class="tag">Deprecated</span>175 <p>This scheme is not in common use anymore. It is documented only for backward compatibility with older events already on the network. New events SHOULD use the marked scheme in §3 instead.</p>176 </div>177 <p>Positional <code>e</code> tags carry no marker. They use the plain <a href="01.html">NIP-01</a> form:</p>178 <div class="crt">179 <div class="titlebar">Wire format - positional e tag</div>180<pre>[<span class="s">"e"</span>, <span class="c"><event-id></span>, <span class="c"><relay-url></span>]</pre>181 </div>182 <p><code>relay-url</code> is the URL of a recommended relay for the reference. Many clients treat this field as optional. Without a marker, the only way to read the tag's meaning is its position in the <code>tags</code> array. This scheme is deprecated because it creates ambiguity that is hard, or impossible, to resolve when an event references another event but is not replying to it.</p>183 <div class="tscroll"><table class="ref">184 <caption>Positional meaning by e-tag count</caption>185 <tr><th>Count of e tags</th><th>Shape</th><th>Meaning</th></tr>186 <tr><td class="btn">none</td><td>(no e tags)</td><td>This event is not a reply to, and does not refer to, any other event.</td></tr>187 <tr><td class="btn">one</td><td><code>["e", <id>]</code></td><td>The id of the event to which this event is a reply.</td></tr>188 <tr><td class="btn">two</td><td><code>["e", <root-id>]</code>, <code>["e", <reply-id>]</code></td><td>First tag is the root of the reply chain. Second tag is the event this note directly replies to.</td></tr>189 <tr><td class="btn">many</td><td><code>["e", <root-id>]</code>, <code>["e", <mention-id>]</code>, …, <code>["e", <reply-id>]</code></td><td>First tag is the root, last tag is the direct reply. Every tag between them is a mention: an id the event cites, which may or may not be in the reply chain.</td></tr>190 </table></div>191192 <h2 class="bar" id="examples"><span class="num">7</span> Worked Example</h2>193 <p>The session below builds the thread from Fig. 10-1 using the marked scheme, then fetches it back, then publishes a quote note with a <code>q</code> tag. Orange lines go to the relay. Blue lines come from the relay.</p>194 <div class="crt">195 <div class="titlebar">Session transcript - wss://relay.example.com</div>196<pre><span class="c">-- Author 22a12a12... publishes the root note --</span>197<span class="send">→ ["EVENT", {"id":"b1a649ebe8…","pubkey":"22a12a12…","kind":1,198 "tags":[],"content":"Running nostr.","sig":"e8551d85…"}]</span>199<span class="recv">← ["OK", "b1a649ebe8…", true, ""]</span>200201<span class="c">-- Author 7a44bb90... replies directly to the root (Reply A) --</span>202<span class="send">→ ["EVENT", {"id":"9f2c11ab…","pubkey":"7a44bb90…","kind":1,203 "tags":[["e","b1a649ebe8…","wss://relay.example.com","root","22a12a12…"],204 ["p","22a12a12…"]],205 "content":"Nice, which relay?","sig":"a02fbd41…"}]</span>206<span class="recv">← ["OK", "9f2c11ab…", true, ""]</span>207208<span class="c">-- Author 3b9012fa... replies to Reply A, not to the root (Reply B) --</span>209<span class="send">→ ["EVENT", {"id":"5cf203de…","pubkey":"3b9012fa…","kind":1,210 "tags":[["e","b1a649ebe8…","wss://relay.example.com","root","22a12a12…"],211 ["e","9f2c11ab…","wss://relay.example.com","reply","7a44bb90…"],212 ["p","7a44bb90…"],["p","22a12a12…"]],213 "content":"Same one I use.","sig":"77c1e0aa…"}]</span>214<span class="recv">← ["OK", "5cf203de…", true, ""]</span>215216<span class="c">-- A client fetches the whole thread by the root id --</span>217<span class="send">→ ["REQ", "thread", {"kinds":[1], "#e": ["b1a649ebe8…"]}]</span>218<span class="recv">← ["EVENT", "thread", {"id":"9f2c11ab…", …}]</span>219<span class="recv">← ["EVENT", "thread", {"id":"5cf203de…", …}]</span>220<span class="recv">← ["EOSE", "thread"]</span>221<span class="send">→ ["CLOSE", "thread"]</span>222223<span class="c">-- A separate note quotes Reply A without replying to it --</span>224<span class="send">→ ["EVENT", {"id":"d40a99c1…","pubkey":"91fedc22…","kind":1,225 "tags":[["q","9f2c11ab…","wss://relay.example.com","7a44bb90…"],226 ["p","7a44bb90…"]],227 "content":"Good point: nostr:nevent1q9f2c11ab…","sig":"f13b0c8e…"}]</span>228<span class="recv">← ["OK", "d40a99c1…", true, ""]</span></pre>229 </div>230231 <h2 class="bar" id="history"><span class="num">8</span> Version History</h2>232 <p>NIP-10 has changed mostly by tightening the marked scheme and clarifying its edge cases. Notable changes, newest first:</p>233 <ul class="patchnotes">234 <li><span class="ver">2025</span><span class="when">2025-02</span>Removed the <code>"mention"</code> e-tag marker; citations now use the <a href="21.html">q tag</a> and <a href="21.html">NIP-21</a> instead (#1750).</li>235 <li><span class="ver">2025</span><span class="when">2025-02</span>Clarified that kind-1 replies must target only other kind-1 events; use <a href="22.html">NIP-22</a> for replies to other kinds (#1690).</li>236 <li><span class="ver">2025</span><span class="when">2025-01</span>Folded the <code>kind:1</code> text-note definition itself into this NIP (#1076).</li>237 <li class="minor"><span class="ver">2024</span><span class="when">2024-11</span>Reorganized the document, moving the deprecated positional scheme to the end.</li>238 <li><span class="ver">2024</span><span class="when">2024-04</span>Added the optional <code>pubkey</code> as the 5th element of the marked e tag, for outbox-model lookups.</li>239 <li class="minor"><span class="ver">2022-2024</span><span class="when">various</span>Typo fixes, JSON reformatting, header-style cleanups, and removal of the per-NIP author byline.</li>240 <li><span class="ver">2023</span><span class="when">2023-02</span>Clarified that the relay-url element should be a valid URL or an empty string, not simply omitted (#291).</li>241 <li><span class="ver">2022</span><span class="when">2022-12</span>Clarified that a direct reply to the thread root uses a single e tag marked <code>"root"</code>, not <code>"reply"</code>.</li>242 <li class="minor"><span class="ver">2022</span><span class="when">2022-11</span>Added the (now-removed) <code>"mention"</code> marker to the marked e-tag scheme.</li>243 <li><span class="ver">Origin</span><span class="when">2022-05-04</span>Robert C. Martin published "NIP-13: Conventions for e and p tags in text events"; renamed to NIP-10 the same day.</li>244 </ul>245246 <div class="credits">247 <h3 class="cardhead">Original Proposal - Credits</h3>248 <table>249 <tr><td>Author</td><td>Robert C. Martin</td></tr>250 <tr><td>First commit</td><td>2022-05-04 — “NIP-13 Conventions for e and p tags in text events” (renamed to NIP-10 the same day)</td></tr>251 <tr><td>Status</td><td>draft - optional</td></tr>252 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/10.md">10.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/10.md">full change history</a></td></tr>253 </table>254 </div>255256 <h2 class="bar"><span class="num">9</span> See Also</h2>257 <ul>258 <li><a href="01.html">NIP-01</a> — the event object, and the base <code>e</code>/<code>p</code>/<code>a</code> tag definitions this NIP builds on.</li>259 <li><a href="21.html">NIP-21</a> — the <code>nostr:</code> URI scheme cited by <code>q</code> tags.</li>260 <li><a href="22.html">NIP-22</a> — the comment kind, used to reply to events that are not <code>kind:1</code>.</li>261 <li><a href="19.html">NIP-19</a> — bech32 encodings such as <code>note</code> and <code>nevent</code> for the raw hex ids used in threads.</li>262 <li><a href="27.html">NIP-27</a> — inline references and mentions inside a note's <code>content</code>.</li>263 <li><a href="65.html">NIP-65</a> — a user's write relays, useful for the outbox-model lookups described in §3.</li>264 </ul>265 </div>266267 <aside>268 <div class="cartridge">269 <div class="inner">270 <h3 class="cardhead">Spec Card</h3>271 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>272 <dl>273 <dt>Status</dt><dd><span class="chip draft">draft</span><span class="chip optional">optional</span></dd>274 <dt>Defines</dt><dd>kind 1 - marked/positional e tags - q tag - p-tag notification</dd>275 <dt>Kind(s)</dt><dd>1</dd>276 <dt>Requires</dt><dd><a href="01.html">NIP-01</a> event format</dd>277 <dt>Pairs with</dt><dd><a href="21.html">NIP-21</a> (q tags) - <a href="22.html">NIP-22</a> (non-kind-1 replies)</dd>278 <dt>Transport</dt><dd>ordinary events - no new messages</dd>279 <dt>Crypto</dt><dd>none beyond <a href="01.html">NIP-01</a> signing</dd>280 <dt>First commit</dt><dd>2022-05-04</dd>281 <dt>Last updated</dt><dd>2025-02-07</dd>282 </dl>283 </div>284 </div>285 </aside>286 </main>287288 <nav class="navbtns">289 <a href="09.html">◀ NIP-09: Event Deletion Request</a>290 <a href="11.html">NIP-11: Relay Information Document ▶</a>291 </nav>292293 <footer class="pagefoot">294 <a href="../index.html">Nostr Protocol Manual</a>295 <span class="pageno">NIP 10 / F4</span>296 </footer>297</div>298299<script src="../assets/webmcp.js" defer></script>300</body>301</html>