API Documentation

REST API, WebSocket feeds, and Nostr relay protocols for building on Nostr Archives.

Base URLs

Service	URL	Protocol
REST API	https://api.nostrarchives.com	HTTP JSON
Live Metrics	wss://api.nostrarchives.com	WebSocket
Search Relay	wss://search.nostrarchives.com	Nostr NIP-50
Feed Relay	wss://feeds.nostrarchives.com	Nostr NIP-01
Scheduler Relay	wss://scheduler.nostrarchives.com	Nostr NIP-42
Indexer Relay	wss://indexer.nostrarchives.com	Nostr NIP-01

REST API

https://api.nostrarchives.com — Rate limit: 120 requests/min per IP

HTTP JSON API for querying events, profiles, search, trending content, analytics, and admin operations.

Health & Stats

GET/health

Health check. Returns 200 OK when the service is running.

Response

JSON

{ "status": "ok" }

GET/v1/stats

Global statistics: total events, unique pubkeys, event kind counts.

Response

JSON

{
  "total_events": 12345678,
  "total_pubkeys": 234567,
  "kinds": { "0": 150000, "1": 8000000, ... }
}

GET/v1/stats/daily

Daily network stats: daily active users, total sats sent, daily posts. Served from Redis HyperLogLog counters for O(1) lookups.

Response

JSON

{
  "daily_active_users": 8234,
  "total_sats_sent": 1456789,
  "daily_posts": 45678
}

GET/v1/stats/follower-cache

Cache monitoring: Web of Trust, follower cache, and profile search cache statistics.

Response

JSON

{
  "wot": {
    "passing_count": 45000,
    "threshold": 21,
    "last_refresh_ago_secs": 120,
    "refresh_interval_secs": 900
  },
  "follower_cache": { ... },
  "profile_search": { ... }
}

GET/v1/crawler/stats

Crawler queue progress and statistics. Returns `{ "enabled": false }` if the crawler is disabled.

Response

JSON

{
  "enabled": true,
  "queue_size": 1234,
  "processed": 56789,
  "errors": 12
}

Events

GET/v1/events

Query events with filters. Returns events enriched with engagement stats (reactions, replies, reposts, zap_sats).

Parameters

Name	Type	Required	Default	Description
pubkey	string	no	—	Filter by author pubkey (hex or npub)
kind	integer	no	—	Filter by event kind
since	integer	no	—	Unix timestamp — events after this time
until	integer	no	—	Unix timestamp — events before this time
search	string	no	—	Full-text search query
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "events": [
    {
      "id": "abc123...",
      "pubkey": "def456...",
      "kind": 1,
      "content": "Hello Nostr!",
      "created_at": 1700000000,
      "reactions": 42,
      "replies": 5,
      "reposts": 3,
      "zap_sats": 21000
    }
  ],
  "count": 1
}

GET/v1/events/{id}

Get a single event by its ID (hex).

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)

Response

JSON

{
  "id": "abc123...",
  "pubkey": "def456...",
  "kind": 1,
  "content": "Hello Nostr!",
  "created_at": 1700000000,
  "tags": [["e", "..."], ["p", "..."]]
}

GET/v1/events/{id}/thread

Get full thread context: parent/root references, replies, reactions, reposts, and zaps.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)
limit	integer	no	50	Max replies (1–500)

Response

JSON

{
  "event": { ... },
  "ancestors": [ ... ],
  "replies": [ ... ],
  "reactions": 42,
  "reposts": 3,
  "zap_sats": 21000
}

GET/v1/pages/note/{id}

Frontend-optimized note detail. Single SQL round-trip returns the event, thread refs, interaction stats, replies, and profile metadata for all involved pubkeys.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)
limit	integer	no	50	Max replies (1–200)

Response

JSON

{
  "event": { ... },
  "replies": [ ... ],
  "profiles": { "<pubkey>": { "name": "...", "picture": "..." } },
  "interactions": { "reactions": 42, "replies": 5, ... }
}

GET/v1/events/{id}/interactions

Lightweight interaction counts for an event. No full events returned.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)

Response

JSON

{
  "reactions": 42,
  "replies": 5,
  "reposts": 3,
  "zap_sats": 21000
}

GET/v1/events/{id}/refs/{ref_type}

Get events that reference a target event, filtered by reference type.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Target event ID (64-char hex)
ref_type	string	yes	—	Reference type(`reply`, `reaction`, `repost`, `zap`, `mention`, `root`)
limit	integer	no	50	Max results (1–500)

Response

JSON

{
  "events": [ ... ],
  "count": 5,
  "ref_type": "reply"
}

Profiles & Social

GET/v1/social/{pubkey}

Follow/follower counts and paginated lists for a pubkey.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Pubkey (hex or npub)
follows_limit	integer	no	100	Max follows to return (1–500)
followers_limit	integer	no	100	Max followers to return (1–500)
follows_offset	integer	no	0	Follows pagination offset
followers_offset	integer	no	0	Followers pagination offset

Response

JSON

{
  "pubkey": "abc123...",
  "follows": { "count": 350, "pubkeys": ["..."] },
  "followers": { "count": 12000, "pubkeys": ["..."] }
}

POST/v1/profiles/metadata

Batch fetch profile metadata for multiple pubkeys. Accepts hex pubkeys or npubs. Cached for 5 minutes.

Request Body

JSON body with array of pubkeys (max 500).

JSON

{ "pubkeys": ["abc123...", "npub1..."] }

Response

JSON

{
  "profiles": [
    {
      "pubkey": "abc123...",
      "display_name": "Alice",
      "name": "alice",
      "preferred_name": "Alice",
      "picture": "https://...",
      "about": "Nostr enthusiast",
      "nip05": "alice@example.com",
      "lud16": "alice@walletofsatoshi.com"
    }
  ]
}

GET/v1/profiles/{pubkey}/notes

Root notes (non-replies) by a specific author, with engagement stats and profile metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Author pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "events": [
    { "id": "...", "content": "...", "reactions": 10, "replies": 2, ... }
  ],
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

GET/v1/profiles/{pubkey}/replies

Replies by a specific author, with engagement stats and profile metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Author pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "events": [ ... ],
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

GET/v1/profiles/{pubkey}/zaps/sent

Zaps sent by a specific pubkey, with recipient metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Sender pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "zaps": [
    { "event": { ... }, "amount_sats": 1000, "recipient": "...", "zapped_event_id": "..." }
  ],
  "total": 42,
  "profiles": { ... }
}

GET/v1/profiles/{pubkey}/zaps/received

Zaps received by a specific pubkey, with sender metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Recipient pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "zaps": [
    { "event": { ... }, "amount_sats": 5000, "sender": "...", "zapped_event_id": "..." }
  ],
  "total": 128,
  "profiles": { ... }
}

GET/v1/profiles/{pubkey}/zap-stats

Zap statistics for a pubkey: total sats sent/received and zap counts.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Pubkey (hex or npub)

Response

JSON

{
  "sent": { "total_sats": 150000, "count": 42 },
  "received": { "total_sats": 500000, "count": 128 }
}

Search

GET/v1/search

Full-text search across profiles and notes. Automatically detects and resolves Nostr entities (npub, nprofile, nevent, note1, 64-char hex).

If the query resolves to a Nostr entity, a `resolved` object is returned instead of search results.

Parameters

Name	Type	Required	Default	Description
q	string	yes	—	Search query
type	string	no	all	Result type filter(`all`, `profiles`, `notes`)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "query": "bitcoin",
  "profiles": [
    { "pubkey": "...", "name": "...", "display_name": "...", "picture": "...", "nip05": "...", "follower_count": 1234 }
  ],
  "notes": [
    { "id": "...", "pubkey": "...", "content": "...", "created_at": 1700000000, "reactions": 10 }
  ]
}

GET/v1/search/suggest

Autocomplete suggestions for search-as-you-type. Returns profile suggestions ranked by prefix match quality and follower count. Also resolves Nostr entities.

Parameters

Name	Type	Required	Default	Description
q	string	yes	—	Search query (min 2 characters)
limit	integer	no	5	Max suggestions (1–10)

Response

JSON

{
  "query": "al",
  "suggestions": [
    { "pubkey": "...", "name": "alice", "display_name": "Alice", "picture": "...", "follower_count": 5000 }
  ]
}

GET/v1/notes/search

Advanced note search with filters for author, reply context, and sort order.

Parameters

Name	Type	Required	Default	Description
q	string	no	—	Full-text search query
exclude	string	no	—	Exclude notes containing this term
author	string	no	—	Filter by author pubkey (hex or npub)
reply_to	string	no	—	Filter to replies to this pubkey (hex or npub)
order	string	no	newest	Sort order(`newest`, `oldest`, `engagement`)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "notes": [
    { "event": { ... }, "reactions": 10, "replies": 2, "reposts": 1, "zap_sats": 5000 }
  ],
  "total": 142,
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

Trending & Leaderboards

GET/v1/notes/top

Top notes ranked by a specific engagement metric within a time range. Aggressively cached in Redis (90s for today, up to 1h for all-time).

Parameters

Name	Type	Required	Default	Description
metric	string	no	reactions	Engagement metric(`reactions`, `replies`, `reposts`, `zaps`)
range	string	no	today	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "metric": "reactions",
  "range": "today",
  "notes": [
    {
      "count": 150,
      "total_sats": 50000,
      "reactions": 150,
      "replies": 20,
      "reposts": 10,
      "zap_sats": 50000,
      "event": { "id": "...", "content": "...", ... }
    }
  ],
  "profiles": { "<pubkey>": { "name": "...", "picture": "..." } }
}

GET/v1/notes/trending

Trending notes ranked by a composite engagement score (reactions + replies + reposts + zap sats). Cached 5 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "notes": [ ... ] }

GET/v1/users/new

Recently joined users (first seen in the last 24 hours). Cached 5 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "users": [ { "pubkey": "...", "name": "...", "created_at": 1700000000 } ] }

GET/v1/users/trending

Trending users ranked by new follower count in the last 24 hours. Cached 24 hours.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "users": [ ... ] }

GET/v1/users/zappers

Top zappers by sats sent or received in a time range.

Parameters

Name	Type	Required	Default	Description
direction	string	no	received	Zap direction(`sent`, `received`)
range	string	no	7d	Time range(`today`, `7d`, `30d`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "direction": "received",
  "range": "7d",
  "zappers": [ { "pubkey": "...", "total_sats": 500000, "zap_count": 42 } ]
}

GET/v1/hashtags/trending

Trending hashtags from the last 24 hours. Cached 10 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	50	Max results (1–50)
offset	integer	no	0	Pagination offset

Response

JSON

{ "hashtags": [ { "tag": "bitcoin", "count": 456 } ] }

GET/v1/hashtags/{tag}/notes

Notes tagged with a specific hashtag, with profile metadata. Cached 5 minutes.

Parameters

Name	Type	Required	Default	Description
tag	string	yes	—	Hashtag (without #)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "hashtag": "bitcoin",
  "notes": [ ... ],
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

Analytics

GET/v1/analytics/daily

Daily analytics for the last N days. Cached 24 hours (immutable once computed).

Parameters

Name	Type	Required	Default	Description
days	integer	no	30	Number of days (1–365)

Response

JSON

{
  "data": [
    { "date": "2025-01-15", "dau": 8234, "posts": 45678, "zap_sats": 1456789 }
  ],
  "range": { "from": "2024-12-16", "to": "2025-01-15" }
}

GET/v1/analytics/top-posters

Authors ranked by number of kind-1 notes published in the time range.

Parameters

Name	Type	Required	Default	Description
range	string	no	7d	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "range": "7d", "authors": [ { "pubkey": "...", "count": 234 } ] }

GET/v1/analytics/most-liked

Authors whose notes received the most reactions (kind-7) in the time range.

Parameters

Name	Type	Required	Default	Description
range	string	no	7d	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "range": "7d", "authors": [ { "pubkey": "...", "count": 567 } ] }

GET/v1/analytics/most-shared

Authors whose notes received the most reposts (kind-6) in the time range.

Parameters

Name	Type	Required	Default	Description
range	string	no	7d	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "range": "7d", "authors": [ { "pubkey": "...", "count": 89 } ] }

GET/v1/clients/leaderboard

Nostr clients ranked by note count and distinct user count. Cached 10 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "clients": [ { "client_name": "Damus", "note_count": 500000, "user_count": 12000 } ] }

GET/v1/clients/{client_name}/users

Top users of a specific Nostr client, ranked by note count. Cached 10 minutes.

Parameters

Name	Type	Required	Default	Description
client_name	string	yes	—	Client name (case-insensitive)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "client_name": "damus",
  "users": [ { "pubkey": "...", "note_count": 1234 } ],
  "profiles": { ... }
}

GET/v1/relays/leaderboard

Top relays ranked by event count. Cached 30 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "relays": [ { "url": "wss://relay.damus.io", "event_count": 5000000 } ] }

Admin

All admin endpoints require NIP-98 HTTP Auth (signed kind-27235 event). Rate limited to 10 req/min per IP.

GET/v1/admin/check-auth

Verify admin authentication status.

Response

JSON

{ "authenticated": true, "pubkey": "abc123..." }

POST/v1/admin/block-pubkey

Block a pubkey. Queues data for deletion.

Request Body

Pubkey to block with reason.

JSON

{ "pubkey": "abc123...", "reason": "spam" }

Response

JSON

{ "blocked": true, "pubkey": "abc123..." }

DELETE/v1/admin/block-pubkey

Unblock a previously blocked pubkey.

Request Body

Pubkey to unblock.

JSON

{ "pubkey": "abc123..." }

Response

JSON

{ "unblocked": true }

GET/v1/admin/blocked-pubkeys

List all blocked pubkeys.

Response

JSON

[ { "pubkey": "abc123...", "reason": "spam", "blocked_at": "2025-01-01T00:00:00Z" } ]

GET/v1/admin/purge-status/{pubkey}

Check data deletion progress for a blocked pubkey.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Pubkey (64-char hex)

Response

JSON

{ "pubkey": "abc123...", "status": "completed", "events_deleted": 1234 }

POST/v1/admin/block-hashtag

Block a hashtag from trending and search results.

Request Body

Hashtag to block with reason.

JSON

{ "hashtag": "spam", "reason": "abuse" }

Response

JSON

{ "blocked": true }

DELETE/v1/admin/block-hashtag

Unblock a hashtag.

Request Body

Hashtag to unblock.

JSON

{ "hashtag": "spam" }

Response

JSON

{ "unblocked": true }

GET/v1/admin/blocked-hashtags

List all blocked hashtags.

Response

JSON

[ { "hashtag": "spam", "reason": "abuse" } ]

POST/v1/admin/block-search-term

Block a search term from returning results.

Request Body

Term to block with reason.

JSON

{ "term": "badterm", "reason": "abuse" }

Response

JSON

{ "blocked": true }

DELETE/v1/admin/block-search-term

Unblock a search term.

Request Body

Term to unblock.

JSON

{ "term": "badterm" }

Response

JSON

{ "unblocked": true }

GET/v1/admin/blocked-search-terms

List all blocked search terms.

Response

JSON

[ { "term": "badterm", "reason": "abuse" } ]

Live WebSockets

WSwss://api.nostrarchives.com/v1/ws/live-metrics

Real-time network metrics stream. Sends an initial snapshot then streams updates every 2–5 seconds. Keepalive ping every 30 seconds.

ProtocolCustom JSON WebSocket

Messages

RelayMetrics update

Current online user count, sats zapped, and notes posted (10-minute sliding window).

{ "online": 1234, "sats": 56789, "notes": 4567 }

WSwss://api.nostrarchives.com/v1/ws/online-users

Live online users stream. Sends an initial snapshot of all active users, then batched updates (max 2/sec).

ProtocolCustom JSON WebSocket

Messages

RelayInitial snapshot

Full list of currently active users.

{ "type": "snapshot", "users": [{ "pubkey": "...", "last_active_ms": 1700000000000, "activity_kind": 1 }] }

RelayBatched update

Incremental updates as users become active.

{ "type": "update", "users": [{ "pubkey": "...", "last_active_ms": 1700000000000, "activity_kind": 1 }] }

Search Relay

wss://search.nostrarchives.com

NIP-50 full-text search relay. Connects at the root path and uses standard Nostr NIP-01 protocol with NIP-50 search extension.

WSwss://search.nostrarchives.com

Full-text search across profiles (kind 0) and notes (kind 1). Supports hashtag filtering via `#t` tags, NIP-19 entity resolution (npub, nprofile, nevent, note1), and 64-char hex lookups.

ProtocolNIP-01 / NIP-50

Messages

ClientSearch request

Subscribe with a NIP-50 search filter. Omit `kinds` to search both profiles and notes.

["REQ", "sub1", { "search": "bitcoin", "kinds": [0, 1], "limit": 20 }]

ClientHashtag search

Search notes by hashtag using the `#t` tag filter.

["REQ", "sub1", { "search": "#bitcoin", "kinds": [1], "#t": ["bitcoin"], "limit": 20 }]

RelayEvent result

Each matching event is sent as a raw Nostr event.

["EVENT", "sub1", { "id": "...", "pubkey": "...", "kind": 1, "content": "...", "created_at": 1700000000, "tags": [...], "sig": "..." }]

RelayEnd of results

Signals all matching events have been sent for this subscription.

["EOSE", "sub1"]

ClientClose subscription

Close an active subscription.

["CLOSE", "sub1"]

Constraints

Max limit: 200 results per subscription
Supported kinds: 0 (profiles), 1 (notes)
NIP-19 entities are auto-resolved (npub, nprofile, nevent, note1)
64-char hex lookups are resolved from the database (no relay fetch)

Feed Relay

wss://feeds.nostrarchives.com

Pre-computed Nostr feeds served via NIP-01 protocol. Connect to specific path-based endpoints for trending notes, user feeds, profile rankings, and hashtags.

WSwss://feeds.nostrarchives.com/users/upandcoming

Emerging users — returns kind-0 profile events for trending new users. Cached 24 hours.

ProtocolNIP-01

Messages

ClientSubscribe

Request emerging user profiles.

["REQ", "sub1", { "limit": 20 }]

RelayProfile event

Kind-0 metadata events for emerging users.

["EVENT", "sub1", { "id": "...", "kind": 0, "content": "{...}", ... }]

WSwss://feeds.nostrarchives.com/profiles/followers

Follower profiles for a pubkey. Returns kind-0 profile events. Cached 10 minutes.

ProtocolNIP-01

Messages

ClientSubscribe

Pass the target pubkey in the `authors` filter to get their followers' profiles.

["REQ", "sub1", { "authors": ["<target_pubkey>"] }]

RelayFollower profile

Kind-0 metadata events for each follower.

["EVENT", "sub1", { "kind": 0, "content": "{...}", ... }]

WSwss://feeds.nostrarchives.com/profiles/{note_type}/{metric}

Ranked notes for a specific profile. Returns the author's top-performing notes sorted by the chosen metric. Cached 5 minutes.

ProtocolNIP-01

Messages

ClientSubscribe

Pass the author's pubkey in the `authors` filter.

["REQ", "sub1", { "authors": ["<pubkey>"] }]

RelayRanked note

Notes arrive ranked by the selected metric.

["EVENT", "sub1", { "kind": 1, "content": "...", ... }]

Constraints

note_type: root, replies
metric: likes, reposts, zaps, replies

Examples

Example: wss://feeds.nostrarchives.com/profiles/root/likes
Example: wss://feeds.nostrarchives.com/profiles/replies/zaps

WSwss://feeds.nostrarchives.com/hashtags/{variant}

Hashtag feeds. Returns kind-30015 interest set events containing hashtag lists. Cached 2 hours.

ProtocolNIP-01

Messages

ClientSubscribe

Empty filter — the variant is determined by the URL path.

["REQ", "sub1", {}]

RelayHashtag set

A kind-30015 event with hashtags as `t` tags.

["EVENT", "sub1", { "kind": 30015, "content": "", "tags": [["t", "bitcoin"], ["t", "nostr"], ...] }]

Constraints

variant: trending (top 100 by 24h count) or all (count > 5)

Examples

Example: wss://feeds.nostrarchives.com/hashtags/trending
Example: wss://feeds.nostrarchives.com/hashtags/all

Scheduler Relay

wss://scheduler.nostrarchives.com

Authenticated relay for scheduling future-dated Nostr events. Events are held and published at their `created_at` timestamp to the author's NIP-65 write relays.

WSwss://scheduler.nostrarchives.com

Connect and authenticate via NIP-42, then submit future-dated events, query your pending events, or cancel them via NIP-09 deletion.

ProtocolNIP-01 / NIP-42 / NIP-09Auth Required

Messages

RelayAuth challenge

Sent immediately on connection. You must respond with a signed auth event before sending other messages.

["AUTH", "<challenge_string>"]

ClientAuth response

Sign a kind-22242 event with the challenge tag to authenticate.

["AUTH", { "kind": 22242, "content": "", "tags": [["relay", "wss://scheduler.nostrarchives.com"], ["challenge", "<challenge_string>"]], "created_at": 1700000000, "pubkey": "...", "id": "...", "sig": "..." }]

ClientSubmit scheduled event

Submit a future-dated event. The `created_at` must be 60 seconds to 90 days in the future. Pubkey must match authenticated user.

["EVENT", { "kind": 1, "content": "Scheduled post!", "created_at": 1700100000, "pubkey": "...", "id": "...", "sig": "...", "tags": [] }]

RelayEvent accepted

Confirmation that the event was accepted for scheduling.

["OK", "<event_id>", true, ""]

ClientCancel scheduled event (NIP-09)

Submit a kind-5 deletion event referencing the scheduled event(s) to cancel.

["EVENT", { "kind": 5, "content": "", "tags": [["e", "<event_id_to_cancel>"]], "pubkey": "...", "id": "...", "sig": "..." }]

ClientQuery pending events

Query your own scheduled events. The `authors` filter is ignored — only your own events are returned.

["REQ", "sub1", { "kinds": [1] }]

ClientClose subscription

Close an active subscription.

["CLOSE", "sub1"]

Constraints

Authentication required (NIP-42) before any operations
created_at must be 60 seconds to 90 days in the future
Maximum 100 pending events per pubkey
Only the event owner can cancel their scheduled events
Events are published to the author's NIP-65 write relays (falls back to top 20 relays)
Publishing task checks every 60 seconds for due events

Indexer Relay

wss://indexer.nostrarchives.com — Rate limit: 30 requests/min per IP

Read-only metadata relay for efficient bulk profile discovery. Only serves kinds 0 (metadata), 3 (contact lists), and 10002 (relay lists).

WSwss://indexer.nostrarchives.com

Query metadata, contact lists, and relay lists for batches of pubkeys. No event publishing allowed.

ProtocolNIP-01

Messages

ClientRequest metadata

Request metadata for a batch of pubkeys. The `authors` filter is required (1–500 hex pubkeys).

["REQ", "sub1", { "authors": ["<pubkey1>", "<pubkey2>", "..."], "kinds": [0, 3, 10002] }]

RelayMetadata event

Raw Nostr events for the requested kinds.

["EVENT", "sub1", { "kind": 0, "pubkey": "...", "content": "{"name":"Alice",...}", ... }]

RelayEnd of stored events

All matching events have been sent.

["EOSE", "sub1"]

ClientClose subscription

Close an active subscription.

["CLOSE", "sub1"]

Constraints

Read-only: EVENT publishing is not allowed
Only kinds 0, 3, 10002 are served
The `authors` filter is required (1–500 hex pubkeys)
Maximum 500 results per REQ
Rate limited: 30 requests/min per IP
Keepalive ping every 30 seconds

Base URLs

Service	URL	Protocol
REST API	https://api.nostrarchives.com	HTTP JSON
Live Metrics	wss://api.nostrarchives.com	WebSocket
Search Relay	wss://search.nostrarchives.com	Nostr NIP-50
Feed Relay	wss://feeds.nostrarchives.com	Nostr NIP-01
Scheduler Relay	wss://scheduler.nostrarchives.com	Nostr NIP-42
Indexer Relay	wss://indexer.nostrarchives.com	Nostr NIP-01

REST API

https://api.nostrarchives.com — Rate limit: 120 requests/min per IP

HTTP JSON API for querying events, profiles, search, trending content, analytics, and admin operations.

Health & Stats

GET/health

Health check. Returns 200 OK when the service is running.

Response

JSON

{ "status": "ok" }

GET/v1/stats

Global statistics: total events, unique pubkeys, event kind counts.

Response

JSON

{
  "total_events": 12345678,
  "total_pubkeys": 234567,
  "kinds": { "0": 150000, "1": 8000000, ... }
}

GET/v1/stats/daily

Daily network stats: daily active users, total sats sent, daily posts. Served from Redis HyperLogLog counters for O(1) lookups.

Response

JSON

{
  "daily_active_users": 8234,
  "total_sats_sent": 1456789,
  "daily_posts": 45678
}

GET/v1/stats/follower-cache

Cache monitoring: Web of Trust, follower cache, and profile search cache statistics.

Response

JSON

{
  "wot": {
    "passing_count": 45000,
    "threshold": 21,
    "last_refresh_ago_secs": 120,
    "refresh_interval_secs": 900
  },
  "follower_cache": { ... },
  "profile_search": { ... }
}

GET/v1/crawler/stats

Crawler queue progress and statistics. Returns `{ "enabled": false }` if the crawler is disabled.

Response

JSON

{
  "enabled": true,
  "queue_size": 1234,
  "processed": 56789,
  "errors": 12
}

Events

GET/v1/events

Query events with filters. Returns events enriched with engagement stats (reactions, replies, reposts, zap_sats).

Parameters

Name	Type	Required	Default	Description
pubkey	string	no	—	Filter by author pubkey (hex or npub)
kind	integer	no	—	Filter by event kind
since	integer	no	—	Unix timestamp — events after this time
until	integer	no	—	Unix timestamp — events before this time
search	string	no	—	Full-text search query
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "events": [
    {
      "id": "abc123...",
      "pubkey": "def456...",
      "kind": 1,
      "content": "Hello Nostr!",
      "created_at": 1700000000,
      "reactions": 42,
      "replies": 5,
      "reposts": 3,
      "zap_sats": 21000
    }
  ],
  "count": 1
}

GET/v1/events/{id}

Get a single event by its ID (hex).

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)

Response

JSON

{
  "id": "abc123...",
  "pubkey": "def456...",
  "kind": 1,
  "content": "Hello Nostr!",
  "created_at": 1700000000,
  "tags": [["e", "..."], ["p", "..."]]
}

GET/v1/events/{id}/thread

Get full thread context: parent/root references, replies, reactions, reposts, and zaps.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)
limit	integer	no	50	Max replies (1–500)

Response

JSON

{
  "event": { ... },
  "ancestors": [ ... ],
  "replies": [ ... ],
  "reactions": 42,
  "reposts": 3,
  "zap_sats": 21000
}

GET/v1/pages/note/{id}

Frontend-optimized note detail. Single SQL round-trip returns the event, thread refs, interaction stats, replies, and profile metadata for all involved pubkeys.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)
limit	integer	no	50	Max replies (1–200)

Response

JSON

{
  "event": { ... },
  "replies": [ ... ],
  "profiles": { "<pubkey>": { "name": "...", "picture": "..." } },
  "interactions": { "reactions": 42, "replies": 5, ... }
}

GET/v1/events/{id}/interactions

Lightweight interaction counts for an event. No full events returned.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Event ID (64-char hex)

Response

JSON

{
  "reactions": 42,
  "replies": 5,
  "reposts": 3,
  "zap_sats": 21000
}

GET/v1/events/{id}/refs/{ref_type}

Get events that reference a target event, filtered by reference type.

Parameters

Name	Type	Required	Default	Description
id	string	yes	—	Target event ID (64-char hex)
ref_type	string	yes	—	Reference type(`reply`, `reaction`, `repost`, `zap`, `mention`, `root`)
limit	integer	no	50	Max results (1–500)

Response

JSON

{
  "events": [ ... ],
  "count": 5,
  "ref_type": "reply"
}

Profiles & Social

GET/v1/social/{pubkey}

Follow/follower counts and paginated lists for a pubkey.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Pubkey (hex or npub)
follows_limit	integer	no	100	Max follows to return (1–500)
followers_limit	integer	no	100	Max followers to return (1–500)
follows_offset	integer	no	0	Follows pagination offset
followers_offset	integer	no	0	Followers pagination offset

Response

JSON

{
  "pubkey": "abc123...",
  "follows": { "count": 350, "pubkeys": ["..."] },
  "followers": { "count": 12000, "pubkeys": ["..."] }
}

POST/v1/profiles/metadata

Batch fetch profile metadata for multiple pubkeys. Accepts hex pubkeys or npubs. Cached for 5 minutes.

Request Body

JSON body with array of pubkeys (max 500).

JSON

{ "pubkeys": ["abc123...", "npub1..."] }

Response

JSON

{
  "profiles": [
    {
      "pubkey": "abc123...",
      "display_name": "Alice",
      "name": "alice",
      "preferred_name": "Alice",
      "picture": "https://...",
      "about": "Nostr enthusiast",
      "nip05": "alice@example.com",
      "lud16": "alice@walletofsatoshi.com"
    }
  ]
}

GET/v1/profiles/{pubkey}/notes

Root notes (non-replies) by a specific author, with engagement stats and profile metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Author pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "events": [
    { "id": "...", "content": "...", "reactions": 10, "replies": 2, ... }
  ],
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

GET/v1/profiles/{pubkey}/replies

Replies by a specific author, with engagement stats and profile metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Author pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "events": [ ... ],
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

GET/v1/profiles/{pubkey}/zaps/sent

Zaps sent by a specific pubkey, with recipient metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Sender pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "zaps": [
    { "event": { ... }, "amount_sats": 1000, "recipient": "...", "zapped_event_id": "..." }
  ],
  "total": 42,
  "profiles": { ... }
}

GET/v1/profiles/{pubkey}/zaps/received

Zaps received by a specific pubkey, with sender metadata.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Recipient pubkey (hex or npub)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset
sort	string	no	recent	Sort order(`recent`, `engagement`)

Response

JSON

{
  "zaps": [
    { "event": { ... }, "amount_sats": 5000, "sender": "...", "zapped_event_id": "..." }
  ],
  "total": 128,
  "profiles": { ... }
}

GET/v1/profiles/{pubkey}/zap-stats

Zap statistics for a pubkey: total sats sent/received and zap counts.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Pubkey (hex or npub)

Response

JSON

{
  "sent": { "total_sats": 150000, "count": 42 },
  "received": { "total_sats": 500000, "count": 128 }
}

Search

GET/v1/search

Full-text search across profiles and notes. Automatically detects and resolves Nostr entities (npub, nprofile, nevent, note1, 64-char hex).

If the query resolves to a Nostr entity, a `resolved` object is returned instead of search results.

Parameters

Name	Type	Required	Default	Description
q	string	yes	—	Search query
type	string	no	all	Result type filter(`all`, `profiles`, `notes`)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "query": "bitcoin",
  "profiles": [
    { "pubkey": "...", "name": "...", "display_name": "...", "picture": "...", "nip05": "...", "follower_count": 1234 }
  ],
  "notes": [
    { "id": "...", "pubkey": "...", "content": "...", "created_at": 1700000000, "reactions": 10 }
  ]
}

GET/v1/search/suggest

Autocomplete suggestions for search-as-you-type. Returns profile suggestions ranked by prefix match quality and follower count. Also resolves Nostr entities.

Parameters

Name	Type	Required	Default	Description
q	string	yes	—	Search query (min 2 characters)
limit	integer	no	5	Max suggestions (1–10)

Response

JSON

{
  "query": "al",
  "suggestions": [
    { "pubkey": "...", "name": "alice", "display_name": "Alice", "picture": "...", "follower_count": 5000 }
  ]
}

GET/v1/notes/search

Advanced note search with filters for author, reply context, and sort order.

Parameters

Name	Type	Required	Default	Description
q	string	no	—	Full-text search query
exclude	string	no	—	Exclude notes containing this term
author	string	no	—	Filter by author pubkey (hex or npub)
reply_to	string	no	—	Filter to replies to this pubkey (hex or npub)
order	string	no	newest	Sort order(`newest`, `oldest`, `engagement`)
limit	integer	no	20	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "notes": [
    { "event": { ... }, "reactions": 10, "replies": 2, "reposts": 1, "zap_sats": 5000 }
  ],
  "total": 142,
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

Trending & Leaderboards

GET/v1/notes/top

Top notes ranked by a specific engagement metric within a time range. Aggressively cached in Redis (90s for today, up to 1h for all-time).

Parameters

Name	Type	Required	Default	Description
metric	string	no	reactions	Engagement metric(`reactions`, `replies`, `reposts`, `zaps`)
range	string	no	today	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "metric": "reactions",
  "range": "today",
  "notes": [
    {
      "count": 150,
      "total_sats": 50000,
      "reactions": 150,
      "replies": 20,
      "reposts": 10,
      "zap_sats": 50000,
      "event": { "id": "...", "content": "...", ... }
    }
  ],
  "profiles": { "<pubkey>": { "name": "...", "picture": "..." } }
}

GET/v1/notes/trending

Trending notes ranked by a composite engagement score (reactions + replies + reposts + zap sats). Cached 5 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "notes": [ ... ] }

GET/v1/users/new

Recently joined users (first seen in the last 24 hours). Cached 5 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "users": [ { "pubkey": "...", "name": "...", "created_at": 1700000000 } ] }

GET/v1/users/trending

Trending users ranked by new follower count in the last 24 hours. Cached 24 hours.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "users": [ ... ] }

GET/v1/users/zappers

Top zappers by sats sent or received in a time range.

Parameters

Name	Type	Required	Default	Description
direction	string	no	received	Zap direction(`sent`, `received`)
range	string	no	7d	Time range(`today`, `7d`, `30d`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "direction": "received",
  "range": "7d",
  "zappers": [ { "pubkey": "...", "total_sats": 500000, "zap_count": 42 } ]
}

GET/v1/hashtags/trending

Trending hashtags from the last 24 hours. Cached 10 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	50	Max results (1–50)
offset	integer	no	0	Pagination offset

Response

JSON

{ "hashtags": [ { "tag": "bitcoin", "count": 456 } ] }

GET/v1/hashtags/{tag}/notes

Notes tagged with a specific hashtag, with profile metadata. Cached 5 minutes.

Parameters

Name	Type	Required	Default	Description
tag	string	yes	—	Hashtag (without #)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "hashtag": "bitcoin",
  "notes": [ ... ],
  "profiles": { "<pubkey>": { "name": "...", ... } }
}

Analytics

GET/v1/analytics/daily

Daily analytics for the last N days. Cached 24 hours (immutable once computed).

Parameters

Name	Type	Required	Default	Description
days	integer	no	30	Number of days (1–365)

Response

JSON

{
  "data": [
    { "date": "2025-01-15", "dau": 8234, "posts": 45678, "zap_sats": 1456789 }
  ],
  "range": { "from": "2024-12-16", "to": "2025-01-15" }
}

GET/v1/analytics/top-posters

Authors ranked by number of kind-1 notes published in the time range.

Parameters

Name	Type	Required	Default	Description
range	string	no	7d	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "range": "7d", "authors": [ { "pubkey": "...", "count": 234 } ] }

GET/v1/analytics/most-liked

Authors whose notes received the most reactions (kind-7) in the time range.

Parameters

Name	Type	Required	Default	Description
range	string	no	7d	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "range": "7d", "authors": [ { "pubkey": "...", "count": 567 } ] }

GET/v1/analytics/most-shared

Authors whose notes received the most reposts (kind-6) in the time range.

Parameters

Name	Type	Required	Default	Description
range	string	no	7d	Time range(`today`, `7d`, `30d`, `1y`, `all`)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "range": "7d", "authors": [ { "pubkey": "...", "count": 89 } ] }

GET/v1/clients/leaderboard

Nostr clients ranked by note count and distinct user count. Cached 10 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "clients": [ { "client_name": "Damus", "note_count": 500000, "user_count": 12000 } ] }

GET/v1/clients/{client_name}/users

Top users of a specific Nostr client, ranked by note count. Cached 10 minutes.

Parameters

Name	Type	Required	Default	Description
client_name	string	yes	—	Client name (case-insensitive)
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{
  "client_name": "damus",
  "users": [ { "pubkey": "...", "note_count": 1234 } ],
  "profiles": { ... }
}

GET/v1/relays/leaderboard

Top relays ranked by event count. Cached 30 minutes.

Parameters

Name	Type	Required	Default	Description
limit	integer	no	100	Max results (1–100)
offset	integer	no	0	Pagination offset

Response

JSON

{ "relays": [ { "url": "wss://relay.damus.io", "event_count": 5000000 } ] }

Admin

All admin endpoints require NIP-98 HTTP Auth (signed kind-27235 event). Rate limited to 10 req/min per IP.

GET/v1/admin/check-auth

Verify admin authentication status.

Response

JSON

{ "authenticated": true, "pubkey": "abc123..." }

POST/v1/admin/block-pubkey

Block a pubkey. Queues data for deletion.

Request Body

Pubkey to block with reason.

JSON

{ "pubkey": "abc123...", "reason": "spam" }

Response

JSON

{ "blocked": true, "pubkey": "abc123..." }

DELETE/v1/admin/block-pubkey

Unblock a previously blocked pubkey.

Request Body

Pubkey to unblock.

JSON

{ "pubkey": "abc123..." }

Response

JSON

{ "unblocked": true }

GET/v1/admin/blocked-pubkeys

List all blocked pubkeys.

Response

JSON

[ { "pubkey": "abc123...", "reason": "spam", "blocked_at": "2025-01-01T00:00:00Z" } ]

GET/v1/admin/purge-status/{pubkey}

Check data deletion progress for a blocked pubkey.

Parameters

Name	Type	Required	Default	Description
pubkey	string	yes	—	Pubkey (64-char hex)

Response

JSON

{ "pubkey": "abc123...", "status": "completed", "events_deleted": 1234 }

POST/v1/admin/block-hashtag

Block a hashtag from trending and search results.

Request Body

Hashtag to block with reason.

JSON

{ "hashtag": "spam", "reason": "abuse" }

Response

JSON

{ "blocked": true }

DELETE/v1/admin/block-hashtag

Unblock a hashtag.

Request Body

Hashtag to unblock.

JSON

{ "hashtag": "spam" }

Response

JSON

{ "unblocked": true }

GET/v1/admin/blocked-hashtags

List all blocked hashtags.

Response

JSON

[ { "hashtag": "spam", "reason": "abuse" } ]

POST/v1/admin/block-search-term

Block a search term from returning results.

Request Body

Term to block with reason.

JSON

{ "term": "badterm", "reason": "abuse" }

Response

JSON

{ "blocked": true }

DELETE/v1/admin/block-search-term

Unblock a search term.

Request Body

Term to unblock.

JSON

{ "term": "badterm" }

Response

JSON

{ "unblocked": true }

GET/v1/admin/blocked-search-terms

List all blocked search terms.

Response

JSON

[ { "term": "badterm", "reason": "abuse" } ]

Live WebSockets

WSwss://api.nostrarchives.com/v1/ws/live-metrics

Real-time network metrics stream. Sends an initial snapshot then streams updates every 2–5 seconds. Keepalive ping every 30 seconds.

ProtocolCustom JSON WebSocket

Messages

RelayMetrics update

Current online user count, sats zapped, and notes posted (10-minute sliding window).

{ "online": 1234, "sats": 56789, "notes": 4567 }

WSwss://api.nostrarchives.com/v1/ws/online-users

Live online users stream. Sends an initial snapshot of all active users, then batched updates (max 2/sec).

ProtocolCustom JSON WebSocket

Messages

RelayInitial snapshot

Full list of currently active users.

{ "type": "snapshot", "users": [{ "pubkey": "...", "last_active_ms": 1700000000000, "activity_kind": 1 }] }

RelayBatched update

Incremental updates as users become active.

{ "type": "update", "users": [{ "pubkey": "...", "last_active_ms": 1700000000000, "activity_kind": 1 }] }

Search Relay

wss://search.nostrarchives.com

NIP-50 full-text search relay. Connects at the root path and uses standard Nostr NIP-01 protocol with NIP-50 search extension.

WSwss://search.nostrarchives.com

Full-text search across profiles (kind 0) and notes (kind 1). Supports hashtag filtering via `#t` tags, NIP-19 entity resolution (npub, nprofile, nevent, note1), and 64-char hex lookups.

ProtocolNIP-01 / NIP-50

Messages

ClientSearch request

Subscribe with a NIP-50 search filter. Omit `kinds` to search both profiles and notes.

["REQ", "sub1", { "search": "bitcoin", "kinds": [0, 1], "limit": 20 }]

ClientHashtag search

Search notes by hashtag using the `#t` tag filter.

["REQ", "sub1", { "search": "#bitcoin", "kinds": [1], "#t": ["bitcoin"], "limit": 20 }]

RelayEvent result

Each matching event is sent as a raw Nostr event.

["EVENT", "sub1", { "id": "...", "pubkey": "...", "kind": 1, "content": "...", "created_at": 1700000000, "tags": [...], "sig": "..." }]

RelayEnd of results

Signals all matching events have been sent for this subscription.

["EOSE", "sub1"]

ClientClose subscription

Close an active subscription.

["CLOSE", "sub1"]

Constraints

Max limit: 200 results per subscription
Supported kinds: 0 (profiles), 1 (notes)
NIP-19 entities are auto-resolved (npub, nprofile, nevent, note1)
64-char hex lookups are resolved from the database (no relay fetch)

Feed Relay

wss://feeds.nostrarchives.com

Pre-computed Nostr feeds served via NIP-01 protocol. Connect to specific path-based endpoints for trending notes, user feeds, profile rankings, and hashtags.

WSwss://feeds.nostrarchives.com/users/upandcoming

Emerging users — returns kind-0 profile events for trending new users. Cached 24 hours.

ProtocolNIP-01

Messages

ClientSubscribe

Request emerging user profiles.

["REQ", "sub1", { "limit": 20 }]

RelayProfile event

Kind-0 metadata events for emerging users.

["EVENT", "sub1", { "id": "...", "kind": 0, "content": "{...}", ... }]

WSwss://feeds.nostrarchives.com/profiles/followers

Follower profiles for a pubkey. Returns kind-0 profile events. Cached 10 minutes.

ProtocolNIP-01

Messages

ClientSubscribe

Pass the target pubkey in the `authors` filter to get their followers' profiles.

["REQ", "sub1", { "authors": ["<target_pubkey>"] }]

RelayFollower profile

Kind-0 metadata events for each follower.

["EVENT", "sub1", { "kind": 0, "content": "{...}", ... }]

WSwss://feeds.nostrarchives.com/profiles/{note_type}/{metric}

Ranked notes for a specific profile. Returns the author's top-performing notes sorted by the chosen metric. Cached 5 minutes.

ProtocolNIP-01

Messages

ClientSubscribe

Pass the author's pubkey in the `authors` filter.

["REQ", "sub1", { "authors": ["<pubkey>"] }]

RelayRanked note

Notes arrive ranked by the selected metric.

["EVENT", "sub1", { "kind": 1, "content": "...", ... }]

Constraints

note_type: root, replies
metric: likes, reposts, zaps, replies

Examples

Example: wss://feeds.nostrarchives.com/profiles/root/likes
Example: wss://feeds.nostrarchives.com/profiles/replies/zaps

WSwss://feeds.nostrarchives.com/hashtags/{variant}

Hashtag feeds. Returns kind-30015 interest set events containing hashtag lists. Cached 2 hours.

ProtocolNIP-01

Messages

ClientSubscribe

Empty filter — the variant is determined by the URL path.

["REQ", "sub1", {}]

RelayHashtag set

A kind-30015 event with hashtags as `t` tags.

["EVENT", "sub1", { "kind": 30015, "content": "", "tags": [["t", "bitcoin"], ["t", "nostr"], ...] }]

Constraints

variant: trending (top 100 by 24h count) or all (count > 5)

Examples

Example: wss://feeds.nostrarchives.com/hashtags/trending
Example: wss://feeds.nostrarchives.com/hashtags/all

Scheduler Relay

wss://scheduler.nostrarchives.com

Authenticated relay for scheduling future-dated Nostr events. Events are held and published at their `created_at` timestamp to the author's NIP-65 write relays.

WSwss://scheduler.nostrarchives.com

Connect and authenticate via NIP-42, then submit future-dated events, query your pending events, or cancel them via NIP-09 deletion.

ProtocolNIP-01 / NIP-42 / NIP-09Auth Required

Messages

RelayAuth challenge

Sent immediately on connection. You must respond with a signed auth event before sending other messages.

["AUTH", "<challenge_string>"]

ClientAuth response

Sign a kind-22242 event with the challenge tag to authenticate.

["AUTH", { "kind": 22242, "content": "", "tags": [["relay", "wss://scheduler.nostrarchives.com"], ["challenge", "<challenge_string>"]], "created_at": 1700000000, "pubkey": "...", "id": "...", "sig": "..." }]

ClientSubmit scheduled event

Submit a future-dated event. The `created_at` must be 60 seconds to 90 days in the future. Pubkey must match authenticated user.

["EVENT", { "kind": 1, "content": "Scheduled post!", "created_at": 1700100000, "pubkey": "...", "id": "...", "sig": "...", "tags": [] }]

RelayEvent accepted

Confirmation that the event was accepted for scheduling.

["OK", "<event_id>", true, ""]

ClientCancel scheduled event (NIP-09)

Submit a kind-5 deletion event referencing the scheduled event(s) to cancel.

["EVENT", { "kind": 5, "content": "", "tags": [["e", "<event_id_to_cancel>"]], "pubkey": "...", "id": "...", "sig": "..." }]

ClientQuery pending events

Query your own scheduled events. The `authors` filter is ignored — only your own events are returned.

["REQ", "sub1", { "kinds": [1] }]

ClientClose subscription

Close an active subscription.

["CLOSE", "sub1"]

Constraints

Authentication required (NIP-42) before any operations
created_at must be 60 seconds to 90 days in the future
Maximum 100 pending events per pubkey
Only the event owner can cancel their scheduled events
Events are published to the author's NIP-65 write relays (falls back to top 20 relays)
Publishing task checks every 60 seconds for due events

Indexer Relay

wss://indexer.nostrarchives.com — Rate limit: 30 requests/min per IP

Read-only metadata relay for efficient bulk profile discovery. Only serves kinds 0 (metadata), 3 (contact lists), and 10002 (relay lists).

WSwss://indexer.nostrarchives.com

Query metadata, contact lists, and relay lists for batches of pubkeys. No event publishing allowed.

ProtocolNIP-01

Messages

ClientRequest metadata

Request metadata for a batch of pubkeys. The `authors` filter is required (1–500 hex pubkeys).

["REQ", "sub1", { "authors": ["<pubkey1>", "<pubkey2>", "..."], "kinds": [0, 3, 10002] }]

RelayMetadata event

Raw Nostr events for the requested kinds.

["EVENT", "sub1", { "kind": 0, "pubkey": "...", "content": "{"name":"Alice",...}", ... }]

RelayEnd of stored events

All matching events have been sent.

["EOSE", "sub1"]

ClientClose subscription

Close an active subscription.

["CLOSE", "sub1"]

Constraints

Read-only: EVENT publishing is not allowed
Only kinds 0, 3, 10002 are served
The `authors` filter is required (1–500 hex pubkeys)
Maximum 500 results per REQ
Rate limited: 30 requests/min per IP
Keepalive ping every 30 seconds