NIP-67: EOSE Completeness Hint
NIP-67 adds optional finish and more hints to EOSE so clients can know whether a relay sent all stored events for a subscription or whether pagination should continue.
EOSE used to say boundary, not completeness
In NIP-01, EOSE marks the end of stored events for a subscription before real-time events continue. It does not tell a client whether the relay sent every stored match or stopped because of an internal cap. That ambiguity is a real pagination problem.
Clients have historically guessed. If fewer events than the requested limit arrive, assume complete. If the limit is filled, paginate with until and ask again. That breaks when a relay's internal cap is lower than the client's requested limit, and it wastes requests when the result count exactly hits the cap.
NIP-67 adds a small hint array to EOSE. It is a tiny protocol change with large practical value for clients that sync history.
finish, more and safe fallback
A relay may send ["EOSE", subscription_id, [hints...]]. The current defined hints are finish and more. finish means the relay has sent every stored event matching the filters and the client should not paginate further. more means the relay holds more matching stored events than it has sent and the client should paginate.
Unknown hints must be ignored. Absence of hints is not definitive, so clients fall back to legacy pagination. The hint applies only to stored events. It does not stop real-time delivery.
The NIP also discusses created_at ties. If several events share the oldest timestamp in a page, naive pagination can skip events. Relays should include boundary-timestamp events where possible and emit finish only when no older events remain.
A fresh pagination NIP from June 2026
NIP-67 is extremely recent. mattn added the visible EOSE Completeness Hint in June 2026 through PR #2317. There is no long adoption history yet, which should be stated plainly.
Its freshness does not make it unimportant. Sync correctness is a core client problem. If a client silently misses older events because it guessed wrong, users see incomplete profiles, broken threads and unreliable archives.
The right reading is practical: implement it where possible, advertise support in NIP-11 and keep fallback behavior for relays that still send old two-element EOSE messages.
The client gets to stop guessing
A relay implementing NIP-67 appends the hint array and advertises 67 in NIP-11 supported_nips. It should send finish only when it knows the stored result set is complete, and more when it knows more stored events remain.
A client implementing it should trust explicit finish, paginate on explicit more, ignore unknown hints and use its old pagination heuristic when hints are absent. This keeps compatibility with older relays and clients.
The UI effect is mostly invisible when it works. History loads completely with fewer wasted requests. That is exactly the kind of infrastructure NIP a reader may never notice but will feel when it is missing.
A wrong hint is worse than no hint
If a relay sends finish incorrectly, a client can miss data with confidence. That is worse than old uncertainty. Relays should be conservative.
There is also boundary-timestamp risk. Pagination around equal created_at values needs care, or clients can lose events even while following the hint model.
Direct sources
The links below are part of the article, not decoration. Start with the official NIP, then read the file history, implementation references and adjacent standards before treating the page as product guidance.
