Mapping Nostr Keys to DNS-Based Internet Identifiers

1 Overview

A Nostr public key is a 64-character hex string. It is precise, but nobody can read it at a glance or remember it. NIP-01 defines the kind 0 user metadata event, where a user publishes a display name, an avatar, and other profile fields.

NIP-05 adds one more optional metadata field: nip05. Its value looks like an email address, for example bob@example.com. A client that sees this field can ask the domain example.com, over plain HTTPS, which public key the name bob belongs to. If the answer matches the event's own pubkey, the client treats the identifier as valid and may display it.

This check needs no new cryptography and no new server type. The domain owner edits or serves one JSON file. Any web host that can serve a static file, or run a small script, can support NIP-05.

NIP-05 does not replace the public key. It only attaches a friendly label to it, and lets anyone confirm that the label and the key currently agree. The label can change or disappear; the public key stays the same identity forever.

2 The nip05 Field and Identifier Format

A client that wants to publish an identifier adds a nip05 key to the stringified JSON in the content field of its kind 0 event. The value is an internet identifier: a string shaped like <local-part>@<domain>.

{
  "name":  "bob",
  "about": <string, optional>,
  "nip05": "bob@example.com"
}

The internet-identifier specification linked above is very liberal about what a local part may contain. NIP-05 is stricter. Follow this rule exactly:

3 The Well-Known Endpoint and Verification Flow

To verify a nip05 value, the client splits it into <local-part> and <domain> at the @ character. It then makes an HTTPS GET request to a fixed, well-known path on that domain:

https://<domain>/.well-known/nostr.json?name=<local-part>

The server answers with a JSON object. It must contain a names key: a mapping from plain names to hex-formatted public keys, in lowercase.

{
  "names": { "<name>": <lowercase hex pubkey>, ... }
}

The client reads the value at names[<local-part>]. If that hex string equals the pubkey of the kind 0 event that carried the nip05 field, the identifier is valid. The client may now display it. If the key is missing, or does not match, the identifier is not valid and the client should not display it as verified.

4 The relays Attribute

The response object may also carry a recommended relays key. It maps each public key to a list of relay URLs where that user's events may be found.

{
  "names": {
    "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9"
  },
  "relays": {
    "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9": [
      "wss://relay.example.com", "wss://relay2.example.com"
    ]
  }
}

A client may use this list the same way it uses a NIP-65 relay list, to find where a newly-discovered user actually publishes. A web server that builds this file dynamically, per query, should also include the matching relays entry for any name it serves, whenever that data is available.

5 Finding Users by Identifier

A client may also run the flow in reverse: start from an identifier typed by a user, such as a search box entry, and end with a full profile.

1. Split the typed identifier into <local-part> and <domain>.
2. Fetch the well-known URL and read the public key from names.
3. Fetch the newest kind 0 event for that public key.
4. Check that the event's own nip05 field matches the identifier the user typed.

This lets a client offer a search box where a user types bob@example.com and the client resolves it straight to a pubkey and a profile.

6 Security Rules and Client Behavior

A few more rules protect users from small mistakes turning into identity confusion:

• Keys are hex, always. The names mapping must use lowercase hex public keys. NIP-19 npub values are for display in a client's user interface only. Never put an npub in a NIP-05 response.
• Follow the pubkey, not the address. Suppose a client resolves bob@bob.com to the key abc...def and a user chooses to follow that profile. The client stores abc...def as the follow target. If bob.com later starts returning a different key, 1d2...e3f, the client must not silently switch the followed key. It should instead stop showing bob@bob.com as a valid label for the old key, because the identifier no longer matches.
• The root identifier. A domain owner who does not want a redundant-looking address like bob@bob.com may register the local part _ instead, giving _@bob.com. Clients should show and treat _@domain as just domain.

Browser CORS policy can block a JavaScript client from reading /.well-known/nostr.json on a domain it does not own. A blocked CORS request looks exactly like a missing file: pure-JavaScript code cannot tell the two apart. If a JS client cannot verify a NIP-05 identifier, it may suggest the user check their server's CORS headers with a command like the one in the worked example below. Domain owners should serve /.well-known/nostr.json with the header Access-Control-Allow-Origin: * so that browser-based clients can read it.

7 Worked Example

Client sees the kind 0 event below and wants to verify the nip05 field.

{
  "pubkey": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9",
  "kind":   0,
  "content": "{\"name\": \"bob\", \"nip05\": \"bob@example.com\"}"
  // id, created_at, tags, sig omitted
}

The identifier splits into local part bob and domain example.com. The client makes this HTTPS request:

→ GET /.well-known/nostr.json?name=bob HTTP/1.1
→ Host: example.com
→ Accept: application/json

← HTTP/1.1 200 OK
← Content-Type: application/json
← Access-Control-Allow-Origin: *
←
← {
←   "names": {
←     "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9"
←   },
←   "relays": {
←     "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9": [
←       "wss://relay.example.com", "wss://relay2.example.com"
←     ]
←   }
← }

-- names.bob equals event.pubkey, so the client marks bob@example.com valid --

If a JavaScript client instead sees a network failure at this step, it cannot tell whether the file is missing or CORS blocked it. The domain owner can check their own server from a terminal:

$ curl -sI https://example.com/.well-known/nostr.json?name=bob | grep -i ^Access-Control
Access-Control-Allow-Origin: *

8 Version History

Notable changes to NIP-05, newest first:

• 20262026-02Made explicit that both hex public keys and local-part names must be lowercase (#2208).
• 20242024-08Added the identification-versus-verification distinction: NIP-05 identifies a key, it does not by itself prove trust.
• 20242024-06Renamed the informal "set_metadata" wording to "user metadata," matching NIP-01 terminology.
• 20242024-03Upgraded the relays attribute from a plain suggestion to recommended.
• 20232023-02A proposed security extension (per-account allowed paths) was merged, then reverted days later. No trace remains in the current spec.
• 20232023-01A short-lived NIP-35 on DNS-identifier reflectivity was merged into NIP-05; the number 35 was later reused for an unrelated proposal (Torrents).
• 20222022-12Clarified that clients must keep following the pubkey, not the nip05 address, if the two ever disagree later; required hex-only keys in responses.
• 20222022-05Added the CORS warning and the Access-Control-Allow-Origin recommendation for JavaScript clients.
• Origin2022-05Migrated into the nostr-protocol/nips repository from the original fiatjaf/nostr repository.

9 See Also

• NIP-01 — defines the kind 0 user metadata event that carries the nip05 field.
• NIP-19 — bech32 npub encoding, for display only; never used inside a NIP-05 response.
• NIP-65 — relay list metadata; a more complete alternative to the optional relays attribute here.
• NIP-39 — linking a profile to other platforms; a related but separate identity-claim mechanism.