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.

nostr-watch’s libraries are published to npm under the @nostrwatch scope and can be used independently of the full monorepo. This guide walks you through checking a single relay with nocap and querying aggregated relay state with route66.
nostr-watch is in alpha. APIs may change between releases. Pin to a specific version in production and review the changelog before upgrading.
1

Prerequisites

Make sure you have the following installed before continuing:
RequirementVersionNotes
Node.js>= 20Managed via Volta or your preferred version manager
pnpm>= 8npm install -g pnpm
GitanyRequired only if cloning the monorepo
Optional:
  • Deno >= 1.4 — required for relaymon and trawler services
  • Docker + Docker Compose — required for docker-stacks infrastructure
2

Install nocap

Install @nostrwatch/nocap and its peer dependency @nostrwatch/websocket:
pnpm add @nostrwatch/nocap @nostrwatch/websocket
3

Run a relay check

Create a file check.ts and add the following:
check.ts
import Nocap from '@nostrwatch/nocap'
import WebsocketAdapterDefault from '@nostrwatch/nocap/adapters/default/WebsocketAdapterDefault'
import DnsAdapterDefault from '@nostrwatch/nocap/adapters/default/DnsAdapterDefault'

const nocap = new Nocap('wss://relay.damus.io')
await nocap.useAdapters([WebsocketAdapterDefault, DnsAdapterDefault])

const result = await nocap.check(['open', 'read', 'dns'])
console.log(result)
// {
//   url: 'wss://relay.damus.io',
//   open: { data: true, duration: 120, status: 'success' },
//   read: { data: true, duration: 80, status: 'success' },
//   dns: { data: { ipv4: ['104.21.x.x'] }, duration: 40, status: 'success' }
// }
Run the check:
npx tsx check.ts
To run every supported check at once (open, read, write, dns, ssl, info, geo), use check('all'):
const result = await nocap.check('all')
The ssl check uses Node.js TLS APIs and is not available in browser environments. nocap logs a warning and skips it when running in a browser.
4

Query aggregated relay state with route66

route66 aggregates NIP-66 monitor events and lets you query relay state without running checks yourself. Install it along with its adapters:
pnpm add @nostrwatch/route66
Then query relay state:
route66-example.ts
import {Route66} from '@nostrwatch/route66'
import {NostrSqliteAdapter} from '@nostrwatch/route66-cacheadapter-nostrsqlite'
import {NostrToolsAdapter} from '@nostrwatch/route66-wsadapter-nostrtools'

const cacheAdapter = new NostrSqliteAdapter()
const websocketAdapter = new NostrToolsAdapter()

const r66 = new Route66({cacheAdapter, websocketAdapter})
await r66.boot()
await r66.ready()

const relays = await r66.relays?.getRelays({network: 'clearnet'})
console.log(relays)
// { 'wss://relay.damus.io': { record: { url: '...', network: 'clearnet', ... } }, ... }
route66 connects to NIP-66 monitoring relays, pulls down existing relay check events, and stores them in the local cache adapter. Queries against the cache answer immediately without hitting the network again.

​
Next steps

nocap

Full API reference: adapters, check keys, custom adapter authoring, and the IResult schema.

route66

RelayService queries, ChronicleService time series, MonitorService subscriptions, and adapter authoring.

auditor

Validate relay NIP conformance against their advertised NIP-11 support.

Build docs developers (and LLMs) love

Get started for freeTalk to us