Setup NIP-05 Nostr Username

This guide shows you how to configure your NIP-05 Nostr identity on your ripsline Virtual Private Node.

What is NIP-05?

NIP-05 is a way to verify your Nostr identity using your domain. Instead of just a long public key, people can find you with a human-readable username like yourname@yourdomain.com

Prerequisites

  • ripsline Virtual Private Node installed and running
  • Your Nostr public key in hex format (64 characters)
  • SSH access to your VPS

Getting Your Nostr Public Key

Finding Your Hex Public Key

Your Nostr public key needs to be in hex format (not npub format).

If you have an npub key:

  1. Go to https://damus.io/key/
  2. Paste your npub1... key
  3. Copy the hex format (64 character string)

From popular Nostr clients:

  • Damus (iOS): Settings → Your profile → Copy your public key → Use converter above
  • Amethyst (Android): Profile → Copy public key → Use converter above
  • Primal: Settings → Keys → Copy public key (hex format)
  • Snort: Settings → Keys & Security → Copy hex public key

Setup Steps

Step 1: Connect to Your VPS via SSH

  • Open Termux (GrapheneOS) or Terminal (Mac/Linux)
  • Connect to your VPS: ssh root@your-vps-ip
  • Enter your ssh passphrase

Step 2: Edit the NIP-05 Configuration File

Open the Nostr identity file with nano editor:

nano /var/www/html/.well-known/nostr.json

Step 3: Configure Your Identity

You'll see a template file that looks like this:

{
  "names": {
    "yourname": "YOUR_HEX_PUBKEY_HERE"
  }
}

Make these changes:

  1. Replace yourname with your desired username (letters and numbers only, no spaces)
  2. Replace YOUR_HEX_PUBKEY_HERE with your actual hex public key (64 characters)

Example:

{
  "names": {
    "satoshi": "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"
  }
}

Step 4: Save and Exit

  • Press Ctrl + X to exit
  • Press Y to confirm save
  • Press Enter to confirm filename

Step 5: Verify Your Configuration

Test that your NIP-05 identifier is working:

  1. Open a web browser
  2. Visit: https://yourdomain.com/.well-known/nostr.json
  3. You should see your username and public key in JSON format

Last Step: Add to Your Nostr Profile

In your Nostr client:

  1. Go to your profile settings
  2. Find the NIP-05 identifier field
  3. Enter: yourname@yourdomain.com
  4. Save your profile
  5. Wait a few minutes for verification

Adding Multiple Users

You can add multiple Nostr identities to the same file:

{
  "names": {
    "alice": "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
    "bob": "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245",
    "carol": "a695f6b60119d9521934a691347d9f78e8770b56da16bb255ee286ddb9fcc1b0"
  }
}

Each person would then use:

  • alice@yourdomain.com
  • bob@yourdomain.com
  • carol@yourdomain.com

Troubleshooting

Verification Not Working

  • Check the file format: Make sure JSON is valid (proper quotes and commas)
  • Wait a few minutes: Some clients cache verification results
  • Test the URL directly: Visit https://yourdomain.com/.well-known/nostr.json in browser
  • Check for typos: Username and public key must be exact

Permission Denied Error

If you get permission errors when editing the file:

sudo nano /var/www/html/.well-known/nostr.json

File Not Found

If the file doesn't exist, create it:

mkdir -p /var/www/html/.well-known
nano /var/www/html/.well-known/nostr.json

Then paste the template and configure it.

SSL/HTTPS Issues

  • Make sure your domain has a valid SSL certificate
  • NIP-05 requires HTTPS to work properly
  • Check that https://yourdomain.com loads without errors

Verification Checklist

Use this to verify your NIP-05 is working:

  1. ✅ Hex public key is 64 characters long
  2. ✅ File is valid JSON (check at jsonlint.com)
  3. ✅ URL loads: https://yourdomain.com/.well-known/nostr.json
  4. ✅ Username matches what you entered in Nostr client
  5. ✅ Domain has valid SSL certificate (HTTPS works)
  6. ✅ Waited 5-10 minutes for client to verify

Privacy Note: Your NIP-05 identifier is public and anyone can look up your Nostr public key using your identifier. This is by design - it helps people verify and find your authentic Nostr account.

Useful Tools

Need Help?