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

URL: https://blog.relayted.de/nip-11-relay-information-document-check/
Published: 2026-11-11
Service: relayted labs

## 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:

```bash
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:

```bash
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:

- `name`, `description`, `contact`: plain strings; keep the name short.
- `pubkey`: the operator's public key as 64 hex characters, not an npub.
- `supported_nips`: a list of integers, for example `[1, 11, 42]`. A relay should at least declare NIP-1.
- `software`: a URL pointing to the relay software.
- `version`: a string.
- `limitation`: an object, see below.

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:

- `max_limit`: the largest `limit` a filter may request.
- `max_subscriptions`: how many subscriptions one connection may hold open.
- `max_subid_length` and `max_message_length`: size limits.
- `auth_required`: whether NIP-42 authentication is needed before the relay serves requests.
- `restricted_writes`: whether only some users may publish.
- `created_at_lower_limit` and `created_at_upper_limit`: the accepted time window for events.
- `min_pow_difficulty`: required proof of work.

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:

- Open one subscription more than `max_subscriptions` and see whether the relay refuses it.
- Send a subscription id just above `max_subid_length`.
- If `auth_required` is `true`, try a read without authenticating.
- Publish an event with a `created_at` outside the declared window.
- If you list NIP-45, send a `COUNT`; if you list NIP-50, try a `search` filter.

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](https://labs.relayted.de/) 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](/test-nostr-relay-api-quick-check/): 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](/nip-01-relay-conformance-check/).

## 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.
