nips/200.md

NIP-200

Nostr relay communication over HTTP(s) (NoH)

draft optional author:yonle

This NIP describes the basic of communicating to relays over HTTP(S) requests.

Communication between clients and relays

Relays may expose NoH endpoints that client could reach. Client may make HTTP requests to each relays endpoint for specified tasks as specified in NIP-11. Relays MAY limit number of requests from specific IP/Client/etc.

Relays must ensure that the NoH endpoints MUST be served with Access-Control-Allow-Origin: * header to ensure it can be validated by pure JS apps running in modern browsers.

From client to relay: getting events and sending event

Client could make a request to req, count or publish endpoint that were specified in /.well-known/nostr.json

When fetching events, Client can optionally specify filters directly into the URI search query:

• <count>?<filter>, or
• <req>?<filter>

<filter> is a querystrings that determines what events will be received in that request. it can have the following attributes:

ids=<a list of event ids separated by commas>&
authors=<a list of lowercase pubkeys separated by commas>&
kinds=<a list of kinds numbers separated by commas>&
%23<single-letter (a-zA-Z)>=<a list of tag values separated by commas. for %23e — a list of event ids, for %23p — a list of event pubkeys>&
since=<an integer unix timestamp in seconds, events must be newer than this to pass>&
until=<an integer unix timestamp in seconds, events must be older than this to pass>&
limit=<maximum number of events relays SHOULD return in the initial query>

Request URL Examples:

• https://my-relay.com/__nostr/req?kinds=0,1&limit=10
• https://my-relay.com/__nostr/req?authors=12345,67890
• https://my-relay.com/__nostr/count?count=100&authors=12345,kinds=0

To send event to relay, Client will need to make POST request to publish endpoint with POST body containing the JSON blob of the event.

From relay to client: sending responses and notices

Every NoH response is a JSON body that contain the following JSON field:

• results: Array of relay response. Usually contain events requested by client.
• count: Integer of event counts.
• notice: Human readable error.

Relay may also respond with HTTP status code:

• 200: OK / Success
• 400: Invalid Request
• 500: Relay/Server error