Nostr Filter Designer

Overview

Construct correct

REQ

When to use

• When building Nostr relay subscriptions or REQ messages
• When querying for events by kind, author, tag, or time range
• When constructing complex queries (threads, feeds, engagement metrics)
• When combining multiple filter conditions with AND/OR logic
• When working with tag filters (

  #e

  ,

  #p

  ,

  #a

  , etc.)

Do NOT use when:

• Publishing events (EVENT messages) -- this skill is read-only queries
• Implementing relay-side filter matching logic
• Working with NIP-42 authentication or NIP-45 counting

Core Semantics

These three rules govern ALL filter behavior. Every mistake traces back to violating one of them.

Rule 1: Single filter = AND

All conditions within one filter object must ALL match. There is no way to express OR within a single filter.

{ "authors": ["<pk>"], "kinds": [1], "#e": ["<eid>"] }

This means: events BY this author AND of kind 1 AND tagging this event. Not "events by this author OR tagging this event."

Rule 2: Multiple filters = OR

A REQ message can contain multiple filter objects. An event matches if it satisfies ANY of them.

[
  "REQ",
  "sub-1",
  { "authors": ["<pk>"], "kinds": [1] },
  { "#p": ["<pk>"], "kinds": [1] }
]

This means: notes BY this author OR notes MENTIONING this author.

Rule 3: Tag filters match the first value only

The

#e

#p

#a

An event with tag

["e", "<id>", "wss://relay.example", "reply"]

{"#e": ["<id>"]}

<id>

Filter Structure

{
  "ids": ["<64-char-hex>..."],
  "authors": ["<64-char-hex>..."],
  "kinds": [<integer>...],
  "#<single-letter>": ["<value>..."],
  "since": <unix-timestamp>,
  "until": <unix-timestamp>,
  "limit": <integer>
}

All fields are optional. Omitted fields impose no constraint.

Field rules

ids

authors

kinds

#<letter>

#e

#p

since

created_at >= since

until

created_at <= until

limit

Workflow

1. Identify what you need

Translate the natural language query into concrete requirements:

• Who: specific authors, or any author?
• What kind: notes (1), reactions (7), reposts (6), zaps (9735), profiles (0)?
• Related to what: specific events (#e), specific people (#p), specific addressable events (#a)?
• When: time-bounded or open-ended?
• How many: limited initial fetch or ongoing subscription?

2. Determine AND vs OR

Ask: "Can a single event satisfy ALL my conditions simultaneously?"

• Yes -> one filter with all conditions (AND)
• No -> multiple filters (OR)

The most common mistake is cramming OR-logic into a single filter. If you need "events by Alice OR events mentioning Alice," that requires two filters.

3. Construct the filter(s)

Build each filter object. For each condition, add the appropriate field. Cross-reference with references/filter-patterns.md for common patterns.

4. Validate

Check each filter against these rules:

• All hex values are exactly 64 characters, lowercase
• Tag filter keys are single letters (

  #e

  , not

  #event

  )
• No NOT/exclusion logic (Nostr filters can't do this)

• since

  and

  until

  are unix timestamps in seconds (not milliseconds)

• limit

  is only used for initial queries, not ongoing subscriptions
• AND/OR semantics match the intent

5. Format as REQ

Wrap in the REQ message format:

["REQ", "<subscription-id>", <filter1>, <filter2>, ...]

Examples

Example 1: Get a full thread (root + all replies)

Need: The root event itself, plus all kind-1 replies that tag it.

A single filter can't do this because the root event won't have an

#e

[
  "REQ",
  "thread-sub",
  { "ids": ["aabb...64chars"] },
  { "kinds": [1], "#e": ["aabb...64chars"] }
]

Filter 1 fetches the root by ID. Filter 2 fetches all kind-1 events that reference it via an

e

Why not one filter?

{"ids": ["aabb..."], "#e": ["aabb..."]}

aabb...

aabb...

Example 2: User's social feed

Need: A user's notes, reposts, and reactions.

All three share the same author, so one filter with multiple kinds works (AND on author, list-match on kinds):

{ "authors": ["<pubkey>"], "kinds": [1, 6, 7], "limit": 50 }

This works because

kinds

authors

Example 3: All engagement on an event

Need: Replies, reactions, zaps, and reposts of a specific event.

All engagement types tag the event via

#e

{ "#e": ["<event-id>"], "kinds": [1, 6, 7, 9735] }

Example 4: Events by author OR mentioning author

Need: Show everything relevant to a user -- their own posts and posts that mention them.

This requires OR (two filters), because an event can't simultaneously be authored by someone AND mention them in a

p

[
  "REQ",
  "user-activity",
  { "authors": ["<pk>"], "kinds": [1] },
  { "#p": ["<pk>"], "kinds": [1] }
]

Common Mistakes

{"authors": ["A"], "#p": ["A"]}

#event

#pubkey

#e

#p

#a

ids

authors

#e

#p

Date.now()

limit

limit

limit

Quick Reference

{"authors": ["<pk>"], "kinds": [1]}

{"authors": ["<pk>"], "kinds": [0]}

{"authors": ["<pk>"], "kinds": [3]}

{"authors": ["<pk>"], "kinds": [10002]}

{"kinds": [1], "#e": ["<eid>"]}

{"kinds": [7], "#e": ["<eid>"]}

{"kinds": [9735], "#e": ["<eid>"]}

{"kinds": [6], "#e": ["<eid>"]}

{"ids": ["<root>"]}

{"kinds": [1], "#e": ["<root>"]}

{"kinds": [1111], "#E": ["<root-id>"]}

{"authors": ["<pk>"], "kinds": [10050]}

{"#e": ["<eid>"], "kinds": [1, 6, 7, 9735]}

{"#p": ["<pk>"]}

{"authors": ["<pk>"], "kinds": [1, 6, 7]}

See references/filter-patterns.md for the full cookbook with advanced patterns and explanations.

Key Principles

1. AND within, OR between -- This is the single most important rule. Every condition in one filter is AND'd. Multiple filters are OR'd. There is no other way to combine conditions.

2. Hex or nothing --

   ids

   ,

   authors

   ,

   #e

   , and

   #p

   values must be exact 64-character lowercase hex strings. No npub, note1, nprofile, or other NIP-19 encodings. Convert first.

3. Tag filters are shallow --

   #e

   matches only the first value (index 0) of

   e

   tags. You cannot filter by relay hints, markers, or other positional tag values. Those must be filtered client-side.

4. No negation -- You cannot exclude events matching a condition. If you need "all kind-1 events except from author X," fetch all kind-1 events and filter client-side.

5. Limit is a suggestion for initial load --

   limit

   tells the relay how many events to return in the initial batch (newest first). It does NOT cap an ongoing subscription. Relays may return fewer than requested.