1NIP-112======34Relay Information Document5--------------------------67`draft` `optional` `relay`89Relays may provide server metadata to clients to inform them of capabilities, administrative contacts, and various server attributes. This is made available as a JSON document over HTTP, on the same URI as the relay's websocket.1011When a relay receives an HTTP(s) request with an `Accept` header of `application/nostr+json` to a URI supporting WebSocket upgrades, they SHOULD return a document with the following structure.1213```json14{15 "name": <string identifying relay>,16 "description": <string with detailed information>,17 "banner": <a link to an image (e.g. in .jpg, or .png format)>,18 "icon": <a link to an icon (e.g. in .jpg, or .png format>,19 "pubkey": <administrative contact pubkey>,20 "self": <relay's own pubkey>,21 "contact": <administrative alternate contact>,22 "supported_nips": <a list of NIP numbers supported by the relay>,23 "software": <string identifying relay software URL>,24 "version": <string version identifier>,25 "terms_of_service": <a link to a text file describing the relay's term of service>26}27```2829Any field may be omitted, and clients MUST ignore any additional fields they do not understand. Relays MUST accept CORS requests by sending `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers`, and `Access-Control-Allow-Methods` headers.3031Field Descriptions32------------------3334### Name3536A relay may select a `name` for use in client software. This is a string, and SHOULD be less than 30 characters to avoid client truncation.3738### Description3940Detailed plain-text information about the relay may be contained in the `description` string. It is recommended that this contain no markup, formatting or line breaks for word wrapping, and simply use double newline characters to separate paragraphs. There are no limitations on length.4142### Banner4344To make nostr relay management more user friendly, an effort should be made by relay owners to communicate with non-dev non-technical nostr end users. A banner is a visual representation of the relay. It should aim to visually communicate the brand of the relay, complementing the text `Description`. [Here is an example banner](https://image.nostr.build/232ddf6846e8aea5a61abcd70f9222ab521f711aa545b7ab02e430248fa3a249.png) mockup as visualized in Damus iOS relay view of the Damus relay.4546### Icon4748Icon is a compact visual representation of the relay for use in UI with limited real estate such as a nostr user's relay list view. Below is an example URL pointing to an image to be used as an icon for the relay. Recommended to be squared in shape.4950```yaml51{52 "icon": "https://nostr.build/i/53866b44135a27d624e99c6165cabd76ac8f72797209700acb189fce75021f47.jpg",53 // other fields...54}55```5657### Pubkey5859An administrative contact may be listed with a `pubkey`, in the same format as Nostr events (32-byte hex for a `secp256k1` public key). If a contact is listed, this provides clients with a recommended address to send encrypted direct messages (See [NIP-17](17.md)) to a system administrator. Expected uses of this address are to report abuse or illegal content, file bug reports, or request other technical assistance.6061Relay operators have no obligation to respond to direct messages.6263### Self6465A relay MAY maintain an identity independent from its administrator using the `self` field, which MUST be a 32-byte hex public key. This allows relays to respond to requests with events published either in advance or on demand by their own key.6667### Contact6869An alternative contact may be listed under the `contact` field as well, with the same purpose as `pubkey`. Use of a Nostr public key and direct message SHOULD be preferred over this. Contents of this field SHOULD be a URI, using schemes such as `mailto` or `https` to provide users with a means of contact.7071### Supported NIPs7273As the Nostr protocol evolves, some functionality may only be available by relays that implement a specific `NIP`. This field is an array of the integer identifiers of `NIP`s that are implemented in the relay. Examples would include `1`, for `"NIP-01"` and `9`, for `"NIP-09"`. Client-side `NIPs` SHOULD NOT be advertised, and can be ignored by clients.7475### Software7677The relay server implementation MAY be provided in the `software` attribute. If present, this MUST be a URL to the project's homepage.7879### Version8081The relay MAY choose to publish its software version as a string attribute. The string format is defined by the relay implementation. It is recommended this be a version number or commit identifier.8283### Terms of Service8485The relay owner/admin MAY choose to link to a terms of service document.8687Extra Fields88------------8990### Server Limitations9192These are limitations imposed by the relay on clients. Your client93should expect that requests exceed these *practical* limitations94are rejected or fail immediately.9596```yaml97{98 "limitation": {99 "max_message_length": 16384,100 "max_subscriptions": 300,101 "max_limit": 5000,102 "max_subid_length": 100,103 "max_event_tags": 100,104 "max_content_length": 8196,105 "min_pow_difficulty": 30,106 "auth_required": true,107 "payment_required": true,108 "restricted_writes": true,109 "created_at_lower_limit": 31536000,110 "created_at_upper_limit": 3,111 "default_limit": 500112 },113 // other fields...114}115```116117- `max_message_length`: the maximum number of bytes for incoming JSON that the relay118will attempt to decode and act upon. When you send large subscriptions, you will be119limited by this value. It also effectively limits the maximum size of any event. Value is120calculated from `[` to `]` after UTF-8 serialization (so some unicode characters121will cost 2-3 bytes). It is equal to the maximum size of the WebSocket message frame.122123- `max_subscriptions`: total number of subscriptions that may be124active on a single websocket connection to this relay. Authenticated clients with a (paid) relationship to the relay125may have higher limits.126127- `max_subid_length`: maximum length of subscription id as a string.128129- `max_limit`: the relay server will clamp each filter's `limit` value to this number.130This means the client won't be able to get more than this number131of events from a single subscription filter. This clamping is typically done silently132by the relay, but with this number, you can know that there are additional results133if you narrow your filter's time range or other parameters.134135- `max_event_tags`: in any event, this is the maximum number of elements in the `tags` list.136137- `max_content_length`: maximum number of characters in the `content`138field of any event. This is a count of unicode characters. After139serializing into JSON it may be larger (in bytes), and is still140subject to the `max_message_length`, if defined.141142- `min_pow_difficulty`: new events will require at least this difficulty of PoW,143based on [NIP-13](13.md), or they will be rejected by this server.144145- `auth_required`: this relay requires [NIP-42](42.md) authentication146to happen before a new connection may perform any other action.147Even if set to False, authentication may be required for specific actions.148149- `payment_required`: this relay requires payment before a new connection may perform any action.150151- `restricted_writes`: this relay requires some kind of condition to be fulfilled to152accept events (not necessarily, but including `payment_required` and `min_pow_difficulty`).153This should only be set to `true` when users are expected to know the relay policy before trying154to write to it -- like belonging to a special pubkey-based whitelist or writing only events of155a specific niche kind or content. Normal anti-spam heuristics, for example, do not qualify.156157- `created_at_lower_limit`: 'created_at' lower limit158159- `created_at_upper_limit`: 'created_at' upper limit160161- `default_limit`: The maximum returned events if you send a filter without a `limit`.162163### Pay-to-Relay164165Relays that require payments may want to expose their fee schedules.166167```yaml168{169 "payments_url": "https://my-relay/payments",170 "fees": {171 "admission": [{ "amount": 1000000, "unit": "msats" }],172 "subscription": [{ "amount": 5000000, "unit": "msats", "period": 2592000 }],173 "publication": [{ "kinds": [4], "amount": 100, "unit": "msats" }],174 },175 // other fields...176}177```178179### Examples180181```yaml182~> curl -H "Accept: application/nostr+json" https://nostr.wine | jq183{184 "contact": "wino@nostr.wine",185 "description": "A paid nostr relay for wine enthusiasts and everyone else.",186 "fees": {187 "admission": [188 {189 "amount": 18888000,190 "unit": "msats"191 }192 ]193 },194 "icon": "https://image.nostr.build/30acdce4a81926f386622a07343228ae99fa68d012d54c538c0b2129dffe400c.png",195 "limitation": {196 "auth_required": false,197 "created_at_lower_limit": 94608000,198 "created_at_upper_limit": 300,199 "max_event_tags": 4000,200 "max_limit": 1000,201 "max_message_length": 524288,202 "max_subid_length": 71,203 "max_subscriptions": 50,204 "min_pow_difficulty": 0,205 "payment_required": true,206 "restricted_writes": true207 },208 "name": "nostr.wine",209 "payments_url": "https://nostr.wine/invoices",210 "pubkey": "4918eb332a41b71ba9a74b1dc64276cfff592e55107b93baae38af3520e55975",211 "software": "https://nostr.wine",212 "supported_nips": [ 1, 2, 4, 9, 11, 40, 42, 50, 70, 77 ],213 "terms_of_service": "https://nostr.wine/terms",214 "version": "0.3.3"215}216217~> curl -H "Accept: application/nostr+json" https://nostr.land | jq218{219 "description": "[✨ NFDB] nostr.land family of relays (fi-01 [tiger])",220 "name": "[✨ NFDB] nostr.land",221 "pubkey": "52b4a076bcbbbdc3a1aefa3735816cf74993b1b8db202b01c883c58be7fad8bd",222 "software": "NFDB",223 "icon": "https://i.nostr.build/b3thno790aodH8lE.jpg",224 "supported_nips": [ 1, 2, 4, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25, 27, 28, 30, 31, 32, 34, 35, 36, 37, 38, 39, 40, 42, 44, 46, 47, 48, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 64, 65, 68, 69, 71, 72, 73, 75, 78, 84, 88, 89, 90, 92, 99 ],225 "version": "1.0.0",226 "limitation": {227 "payment_required": true,228 "max_message_length": 65535,229 "max_event_tags": 2000,230 "max_subscriptions": 200,231 "auth_required": false232 },233 "payments_url": "https://nostr.land",234 "fees": {235 "subscription": [236 {237 "amount": 4000000,238 "unit": "msats",239 "period": 2592000240 }241 ]242 },243 "terms_of_service": "https://nostr.land/terms"244}245```