Nostr Filters

Overview

Filters are used in the Nostr protocol to query and subscribe to specific events from relays. When a client wants to request events, it sends a filter object that defines criteria for the events it wishes to receive. Relays then return events that match the filter criteria, both from their stored history and in real-time as new events arrive.

Filter Structure

A filter is a JSON object with the following possible attributes:

Attribute	Type	Description
ids	array of strings	List of event IDs (64-character hex strings)
authors	array of strings	List of pubkeys (64-character hex strings)
kinds	array of integers	List of event kinds
#<tag>	array of strings	List of values for a specific tag (e.g., #e, #p)
since	integer	Unix timestamp (seconds), matching events with created_at >= this value
until	integer	Unix timestamp (seconds), matching events with created_at <= this value
limit	integer	Maximum number of events to return in the initial query

How Filters Work

Matching Rules

• List Attributes (ids, authors, kinds, and tag filters like #e):

  • An event matches if its value is contained in the list
  • For tags, the event must have at least one tag value matching one value in the filter list

• Time Range (since and until):

  • Events match if: since <= created_at <= until

• Multiple Conditions:

  • Within a single filter, all conditions must be satisfied (logical AND)
  • If multiple filters are provided, an event matches if it satisfies any filter (logical OR)

Special Considerations

• The ids, authors, #e, and #p filter lists must contain exact 64-character lowercase hex values
• The limit property only applies to the initial query and is ignored for ongoing subscriptions
• When limit is used, relays should return the most recent n events, typically in reverse chronological order

Using Filters in Client-Relay Communication

Filters are used in the REQ message from clients to relays:

["REQ", <subscription_id>, <filter1>, <filter2>, ...]

Where:

• <subscription_id> is a string identifying the subscription
• <filter1>, <filter2>, etc. are filter objects as described above

Filter Examples

Example 1: Get the latest 10 text notes

{
  "kinds": [1],
  "limit": 10
}

Example 2: Get events by a specific author of kinds 0, 1, or 3

{
  "authors": ["79dff8f82963424e0bb02708a22e44b4980893e3a4be0fa3cb60a43b946764e3"],
  "kinds": [0, 1, 3]
}

Example 3: Get replies to a specific event

{
  "kinds": [1],
  "#e": ["4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65"]
}

Example 4: Get events mentioning a user within a time range

{
  "#p": ["f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca"],
  "since": 1672527600,
  "until": 1675206000
}

Example 5: Multiple filters (OR condition)

[
  {
    "authors": ["79dff8f82963424e0bb02708a22e44b4980893e3a4be0fa3cb60a43b946764e3"],
    "kinds": [0]
  },
  {
    "#p": ["79dff8f82963424e0bb02708a22e44b4980893e3a4be0fa3cb60a43b946764e3"],
    "kinds": [1],
    "since": 1672527600
  }
]

This example would match either:

1. Kind 0 events by the specified author, OR
2. Kind 1 events mentioning the specified author since January 1, 2023

References

• NIP-01: Basic protocol flow description