relayted blog

NIP guide

NIP-11 for relay operators: what your relay says about itself

labsPublished 3 min read
NIP-11 for relay operators: what your relay says about itself

Short answer

NIP-11 is the JSON document a relay serves over HTTP when a client sends Accept: application/nostr+json. It needs CORS headers so web clients can read it, correctly typed fields (supported_nips as integers, pubkey as hex) and limitation values that match real behaviour. Fetch it with curl, then test each advertised limit by hand or with the labs Quick Check and Conformance tests.

How clients fetch it

The document lives at the same address as the relay, requested over HTTP(S) instead of WebSocket with the header Accept: application/nostr+json. For wss://relay.example.com the document comes from https://relay.example.com. Look at your own in one line:

curl -H 'Accept: application/nostr+json' https://relay.example.com

CORS is not optional

Web clients run in a browser, and the browser only lets them read the document if the response carries CORS headers, above all Access-Control-Allow-Origin. NIP-11 requires relays to accept CORS requests. Without the header a relay can work for native apps and still look empty to every web client: no name, no supported NIPs, no limits. Test it with an Origin header the way a browser sends it:

curl -i -H 'Accept: application/nostr+json' -H 'Origin: https://example.com' https://relay.example.com

Look for Access-Control-Allow-Origin in the response headers.

The fields and their types

Any field may be omitted, but a field that is present should have the right type:

Typical mistakes are NIP numbers as strings ("11" instead of 11), an npub in pubkey, or a document served with an unusual content type.

limitation: promises clients act on

The limitation object tells clients how to behave so they do not run into walls. Common fields:

A client that trusts max_subscriptions: 20 opens 20 and expects them to work. If the real limit is 10, or there is none, the document is wrong, and users see odd behaviour that is hard to trace.

Advertised versus observed

The useful question is not only whether the document is valid, but whether the relay does what it says. A few checks you can do by hand:

When a test and the document disagree, fix one of them. Often the document was copied from a default config and never updated after the limits changed.

Checking it with labs

The Quick Check of labs fetches your NIP-11 document the way a browser does, including an Origin header, checks CORS, field types and the declared NIPs, and measures the connection phases on the way. The Conformance check compares the limitation promises and the declared NIPs with the observed behaviour and lists each item as advertised, observed and verdict. From a script this is the call described in How to test a Nostr relay with one API call: 200 Payloads (0.02 EUR) for the Quick Check, 800 Payloads (0.08 EUR) for Conformance.

If your relay requires NIP-42, labs answers the challenge with a throwaway key. If a meaningful test is not possible, the run stops. Part 2 of this series covers the base protocol: NIP-01.

FAQ

How do I fetch the NIP-11 document of a relay?

Request the relay address over HTTP(S) with the header Accept: application/nostr+json, for example curl -H "Accept: application/nostr+json" https://relay.example.com.

Why do web clients not see my relay information?

Usually because the response has no Access-Control-Allow-Origin header. NIP-11 requires relays to accept CORS requests.

Should pubkey be an npub?

No. The pubkey field holds the operator key as 64 hex characters.

Which limits do clients rely on?

Clients act on limitation fields such as max_subscriptions, max_limit, max_subid_length and auth_required, so they must match the real behaviour of the relay.

How can I check my relay automatically?

The labs Quick Check fetches the document like a browser and checks CORS and field types. The Conformance check compares advertised and observed limits.