Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sandwichfarm/nostr-watch/llms.txt

Use this file to discover all available pages before exploring further.

Monitors are services that periodically check Nostr relays and publish their findings as signed NIP-66 events. Each monitor announces itself with a kind 10166 event and publishes kind 30166 status events for every relay it checks. The rstate aggregation engine tracks these monitors, scores their reliability, and exposes the results through the endpoints documented here. The relaymon service is the reference monitor implementation used in the nostr.watch network. Multiple independent monitors operate across different geographic regions. Their combined observations form the consensus dataset that the rest of the API serves.
Monitor pubkeys are stable Nostr public keys in hex format. You can query individual monitors by pubkey to inspect their coverage and reliability scores.

​
GET /monitors

List all known monitors with their reliability scores, sorted by last seen (most recent first). Response: 
{
  "monitors": [],
  "total": 12,
  "analytics": []
}
​
monitors
object[]
Array of monitor objects. Each monitor includes its pubkey, last seen timestamp, declared check frequency, and network coverage.
​
total
number
Total number of known monitors.
​
analytics
object[]
Reliability analytics for each monitor. Includes coverage, consistency, and timeliness scores.
curl https://api.nostr.watch/v2/monitors

​
GET /monitors/:pubkey

Get detailed information about a specific monitor by its hex pubkey. Path parameters:
​
pubkey
string
required
The monitor’s Nostr pubkey in hex format (64 hex characters).
Response: { monitor, analytics }
​
monitor
object
The monitor’s configuration derived from its kind 10166 event: pubkey, frequency, networks covered, check types, timeouts, and optional geolocation.
​
analytics
object
Reliability analytics for this monitor:
curl https://api.nostr.watch/v2/monitors/a462e2abe80d79bb765e95eed68e5e82d6dcf7a26fd6bc2a9c42ad58a81da2c7

​
GET /monitors/:pubkey/analytics

Get analytics data for a specific monitor without the full monitor object. Path parameters:
​
pubkey
string
required
The monitor’s Nostr pubkey in hex format.
Response: Analytics object with coverage, consistency, and timeliness scores.

​
GET /monitors/analytics

Get aggregated analytics across all monitors. Useful for understanding the overall health of the monitoring network. Response: Array of analytics objects, one per monitor. 
curl https://api.nostr.watch/v2/monitors/analytics

​
GET /policy

Get the current aggregation policy. The policy controls how rstate combines observations from multiple monitors to produce consensus values. Response: 
{
  "policy": {
    "quorum": 0.5,
    "labelQuorum": 0.4,
    "madScale": 2.0,
    "weights": {
      "recency": 0.6,
      "reliability": 0.4
    }
  }
}
​
policy.quorum
number
Minimum fraction of monitors that must report a value for it to be included in the aggregated result (0–1).
​
policy.labelQuorum
number
Minimum support ratio for label values (NIP-32 L/l tags) to be included in aggregated output (0–1).
​
policy.madScale
number
Median Absolute Deviation scale factor used for numeric outlier rejection. Higher values are more permissive.
​
policy.weights
object
curl https://api.nostr.watch/v2/policy

​
PUT /policy

Update the aggregation policy. This endpoint requires NIP-98 HTTP authentication and the caller’s pubkey must be in the server’s allowedPubkeys configuration.
This endpoint modifies how all relay data is aggregated. Only administrators with an authorized pubkey can call it. Changing quorum to a very high value may result in empty relay results if insufficient monitors agree.
Headers:
HeaderValue
AuthorizationNostr <base64-encoded-signed-kind-27235-event>
Content-Typeapplication/json
Request body:
​
quorum
number
New quorum threshold (0–1).
​
labelQuorum
number
New label quorum threshold (0–1).
​
madScale
number
New MAD scale factor for outlier detection.
​
weights
object
New weighting object with recency and reliability fields (must sum to 1).
Response: { success, policy, message } 
import { finishEvent, getPublicKey } from 'nostr-tools'

async function updatePolicy(newPolicy: object, privateKey: Uint8Array) {
  const authEvent = finishEvent({
    kind: 27235,
    created_at: Math.floor(Date.now() / 1000),
    tags: [
      ['u', 'https://api.nostr.watch/v2/policy'],
      ['method', 'PUT'],
    ],
    content: '',
  }, privateKey)

  const authHeader = `Nostr ${btoa(JSON.stringify(authEvent))}`

  return fetch('https://api.nostr.watch/v2/policy', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': authHeader,
    },
    body: JSON.stringify(newPolicy),
  }).then(r => r.json())
}

​
What monitors report

A monitor’s kind 10166 announcement event documents its configuration. Key fields relevant to understanding reliability scores:
FieldTagMeaning
Check frequencyfrequencyHow often the monitor runs checks, in seconds
NetworksnWhich networks the monitor covers: clearnet, tor, i2p
Check typescWhich checks are performed: open, read, write, ssl, dns, geo, info
TimeoutstimeoutPer-check timeout in ms
LocationgMonitor’s geographic location as a geohash
Reliability scores reflect three dimensions: how many relays the monitor covers (coverage), how closely its observations match other monitors (consistency), and whether it publishes at its declared frequency (timeliness).
To discover monitors programmatically via raw Nostr rather than the REST API, query kind 10166 events from wss://relay.nostr.watch or wss://relaypag.es. See Querying NIP-66 data for examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us