• Your own NIP-05 (name@yourdomain) in 10 minutes, and why it shows a red X
  • What clients do
  • Setup steps
  • Why it shows a red X / doesn’t verify
  • Why bother
  • Checklist

§Your own NIP-05 (name@yourdomain) in 10 minutes, and why it shows a red X

NIP-05 maps a human-readable name like bob@example.com to your Nostr public key. It is not a blue check from anyone. It just proves that whoever controls example.com vouches for that key. And because you can repoint it later, it’s your best tool if you ever have to move to a new key.

§What clients do

When your profile (kind 0) says "nip05": "bob@example.com", a client fetches:

https://example.com/.well-known/nostr.json?name=bob

and expects JSON like:

{
  "names": { "bob": "<your pubkey in HEX>" },
  "relays": { "<your pubkey in HEX>": ["wss://relay.example", "wss://nos.lol"] }
}

If names.bob equals your pubkey, you get the checkmark. relays is optional but helps clients find your notes.

§Setup steps

1. Get your hex pubkey. Your npub converted to hex: 64 characters, 0-9 and a-f. Most clients show it in settings, or use any npub-to-hex converter.
2. Create the file /.well-known/nostr.json on your site with the JSON above. Static hosting (GitHub Pages, Netlify, Cloudflare Pages, your own server) is fine. The ?name= part can be ignored if the file lists everyone.
3. Add the CORS header Access-Control-Allow-Origin: * for that path. Web clients need it.
4. Set it in your profile: put bob@example.com in the NIP-05 field of your client and save.
5. Root name: use _ as the name ("_": "<hex>") and set _@example.com. Many clients then show just example.com.

§Why it shows a red X / doesn’t verify

• npub instead of hex in the JSON. The most common mistake.
• Missing CORS header. Works in mobile apps, fails in web clients.
• Redirects. The spec says clients must NOT follow redirects, so example.com -> www.example.com or http -> https redirects on that path break it. Serve the file on the exact host in your NIP-05.
• Wrong content type or HTML error page. Open the URL in a browser: you should see raw JSON, not a 404 page.
• Caching. Some clients cache results for hours. Re-check later, or in a different client.
• Case. Use lowercase names (a-z0-9-_.) for best results.

§Why bother

• People can find you by a name they can type.
• If your key ever leaks, you point the name at your new key and announce it. Followers who check the NIP-05 see the switch.
• Don’t use a NIP-05 from a provider you don’t control as your only identity anchor. They can take it away.

§Checklist

• [ ] https://yourdomain/.well-known/nostr.json?name=you returns raw JSON
• [ ] Hex pubkey, not npub
• [ ] Access-Control-Allow-Origin: *
• [ ] No redirects on that URL
• [ ] Profile NIP-05 field saved and republished

More guides in my index (see profile). Questions? Reply and I’ll add them. Zaps keep these coming.