Standard-86-Relay

A standard Nostr relay with NIP-86 Management API support built on khatru.

Features

• NIP-86 Management API: Full support for relay management via HTTP/JSON-RPC
• NIP-98 Authentication: Secure admin authentication using signed Nostr events
• BoltDB Storage: Embedded key-value storage for events and management data
• Negentropy Sync: Efficient event synchronization with other relays
• Dual Mode Operation: Choose between blacklist (ban) or allowlist (whitelist) modes

Environment Variables

Variable	Description	Default
PUBKEY	Relay operator pubkey (hex format) - becomes the primary admin	Required
ADMIN_PUBKEYS	Additional admin pubkeys (comma-separated hex)	Optional
NAME	Relay name (NIP-11)	Standard Relay
DESCRIPTION	Relay description (NIP-11)	Empty
ICON	Relay icon URL (NIP-11)	Empty
SERVICE_URL	Public-facing WebSocket URL (e.g. wss://your-relay.example.com). Set when behind a reverse proxy so NIP-98 auth uses the correct URL	auto-detected
PORT	HTTP server port	3334
DB_PATH	Path to BoltDB database file	./data/relay.db
ALLOWLIST_MODE	Enable allowlist mode (true/false)	false

Operating Modes

Blacklist Mode (Default)

In blacklist mode, all pubkeys can publish events unless explicitly banned:

• Use banpubkey to block a pubkey from publishing
• Use allowpubkey to unban a previously banned pubkey
• listbannedpubkeys returns all banned pubkeys

Allowlist Mode

When ALLOWLIST_MODE=true, only explicitly allowed pubkeys can publish:

• On startup, operator and admin pubkeys are automatically added to the allowlist
• Use allowpubkey to add a pubkey to the allowlist
• Use listallowedpubkeys to view all allowed pubkeys
• Pubkeys not in the allowlist receive "pubkey not in allowlist" rejection

NIP-86 API Methods

All methods require NIP-98 authentication with an admin pubkey.

Pubkey Management

Method	Description
banpubkey	Ban a pubkey from publishing (params: [pubkey, reason?])
allowpubkey	Add to allowlist AND remove from ban list (params: [pubkey, reason?])
listbannedpubkeys	List all banned pubkeys with reasons
listallowedpubkeys	List all allowed pubkeys with reasons

Event Management

Method	Description
banevent	Ban an event by ID (params: [id, reason?])
allowevent	Remove event from ban list (params: [id, reason?])
listbannedevents	List all banned event IDs with reasons

Relay Configuration

Method	Description
changerelayname	Update relay name (params: [name])
changerelaydescription	Update relay description (params: [description])
changerelayicon	Update relay icon URL (params: [url])

Admin Management

Method	Description
grantadmin	Grant admin access to a pubkey (params: [pubkey, methods?])
revokeadmin	Revoke admin access (params: [pubkey, methods?])

Quick Start

Using Docker

docker build -t standard-86-relay .
docker run -d \
  -e PUBKEY=your_hex_pubkey \
  -e NAME="My Relay" \
  -p 3334:3334 \
  -v relay-data:/app/data \
  standard-86-relay

Using Docker Compose

cp .env.example .env
# Edit .env with your pubkey and settings
docker compose up -d

From Source

go build -o relay .
PUBKEY=your_hex_pubkey ./relay

Example API Call

# Create NIP-98 auth event and call API
curl -X POST http://localhost:3334 \
  -H "Content-Type: application/nostr+json+rpc" \
  -H "Authorization: Nostr <base64-encoded-signed-event>" \
  -d '{"method":"listbannedpubkeys","params":[]}'

Related Projects

• relay-manager - Web UI for managing this relay
• khatru - The underlying relay framework