NIP-17: Private Direct Messages - A Complete Guide

Learn about NIP-17, the secure replacement for NIP-04, and how to migrate your private messaging in Nostr

NIP-17 represents a significant security upgrade to how private messages work in Nostr. This guide explains why you should care about this protocol improvement, how to migrate from the old NIP-04 standard, and practical steps to secure your communications.

What is NIP-17?

NIP-17 is a Nostr protocol specification that defines Private Direct Messages using a dual-layer encryption system called “seal + gift wrap.” It was created to address fundamental security flaws in the previous NIP-04 encryption method.

Unlike NIP-04, which used a single layer of AES-256-CBC encryption, NIP-17 uses:

1. Seal (kind 13) — an inner layer that encrypts the message and hides which key signed it
2. Gift wrap (kind 1059) — an outer envelope signed by a throwaway key, so your real identity never appears on the event that relays store

This layering means:

• Message content remains private
• Relays cannot see who sent a message — the gift wrap is signed by a random one-time key, not by you
• Timestamps are randomised, so message timing is harder to correlate

Why NIP-17 Matters: The NIP-04 Security Problem

NIP-04 was Nostr’s original direct message protocol, but it has several critical security issues that make it unsuitable for truly private communication.

Comparison: NIP-04 vs NIP-17

The Core Problem with NIP-04

NIP-04 messages expose who is talking to whom to every relay that stores them. (Nostr has no blockchain — events simply sit on relays, and anyone may read from a relay.) While the message body is encrypted, the envelope contains:

# NIP-04 Event Structure (simplified)
{
  "pubkey": "<sender_public_key>",      # Anyone can see who sent this
  "tags": [["p", "<recipient_pubkey>"]], # Anyone can see who received it
  "content": "<encrypted_content>"       # Only content is hidden
}

This means relay operators, network observers, and data scrapers can:

• Build social graphs showing who communicates with whom
• Track communication patterns and frequencies
• Infer relationships from message timing

NIP-17 solves this by wrapping the entire message structure in an additional encryption layer, making it impossible to see sender or recipient information without the decryption key.

How NIP-17 Works: Seal + Gift Wrap

Understanding the technical implementation helps appreciate the security improvements.

The Gift Wrap Layer (Outer)

The gift wrap is the outer envelope that hides all metadata. It’s encrypted to a special “gift wrap key” derived from the recipient’s public key. This layer contains:

• A random public key (not linked to the real sender)
• The recipient’s public key
• A timestamp
• The sealed inner message

The Seal Layer (Inner)

Inside the gift wrap sits the seal, which contains the actual message. This layer:

• Is encrypted using a fresh ephemeral key pair
• Contains the sender’s real public key
• Includes the message content
• Has its own timestamp for replay protection

Key Benefits

1. Sender privacy: Nobody except the recipient can determine who sent the message. The recipient, however, is named in a plaintext p tag that relays must be able to read.
2. Unlinkability: Each message is signed by a fresh one-time key, so messages from the same sender do not obviously belong together.
3. No forward secrecy: NIP-44 derives its conversation key from two static keys, so an attacker who later obtains your nsec can decrypt every message they saved. The one-time keys hide who sent a message; they do not protect past messages. Delete old conversations if that matters to you.

Delivery: The DM Relay List (Kind 10050)

Seal and gift wrap describe how a message is packaged. A third piece — the kind 10050 event — describes where it is delivered. It is a small, public list of the relays that accept your private messages.

The spec is strict about this: senders MUST publish gift wraps only to the relays in the recipient’s kind 10050 list. If you have never published one, the spec treats you as “not ready to receive messages” and clients shouldn’t even try — so DMs addressed to you are silently never delivered. There is no error on either side.

Two practical rules:

• Publish one before expecting any NIP-17 DMs (see Step 3 of the migration guide below)
• Keep it small — the spec recommends 1-3 relays, and every relay you list gets to see who is sending you messages

Migration Guide: Switching from NIP-04 to NIP-17

Migrating to NIP-17 is straightforward with modern Nostr clients. Here’s how to make the switch.

Step 1: Check Your Client Support

Before migrating, verify your client supports NIP-17:

Step 2: Enable NIP-17 in Your Client

Damus (iOS/macOS)

1. Open Settings → Privacy & Security
2. Scroll to “Message Encryption”
3. Toggle “Use NIP-17 for new messages” to ON
4. Your new DMs will use NIP-17 automatically

Note: Older NIP-04 messages remain readable but new messages use NIP-17.

Amethyst (Android)

1. Go to Settings → Messages
2. Enable “Use NIP-17 for DMs”
3. Restart the app for full effect

Primal (iOS/Android/Web)

1. Navigate to Settings → Privacy
2. Under “Direct Messages,” select “NIP-17 (Recommended)”
3. Changes apply immediately to new conversations

Step 3: Publish Your DM Relay List (Kind 10050)

NIP-17 senders deliver only to the relays you list in your kind 10050 event — without one, messages to you are silently dropped (see Delivery: The DM Relay List above).

1. In your client, look for the DM, private-messages, or messaging-relay setting
2. Add one to three relays that accept gift wraps (kind 1059) — some relays reject them
3. Save — your client publishes the kind 10050 list for you

Some clients publish this list automatically when you enable NIP-17. Don’t assume: verify delivery in Step 5 before relying on it.

Step 4: Communicate with Your Contacts

NIP-17 only works if both parties have NIP-17 support. Send a note to frequent contacts:

nostr:note1... # Migration message template

"Hey! I'm upgrading to NIP-17 for better privacy in our DMs.
Please update your Nostr client if you haven't already.
Our future messages will be more secure!"

Step 5: Verify Migration Success

To confirm NIP-17 is working:

1. Send a test message to yourself or a friend
2. Check the event kind (should be 1059 for gift wraps)
3. Look for the kind: 1059 in message details
4. The p tag should point to a random ephemeral key, not your friend’s real key

// Example NIP-17 event (simplified)
{
  "kind": 1059, // Gift wrap event
  "pubkey": "<random_ephemeral_key>", // Not the real sender!
  "tags": [["p", "<recipient_pubkey>"]],
  "content": "<encrypted_seal_content>"
}

Client-Specific Setup Guides

Damus

Damus made NIP-17 the default for new direct messages in recent versions. If you’re on an older version:

1. Update to the latest Damus from App Store
2. NIP-17 is automatically enabled for new conversations
3. Check message details (tap and hold) to see “NIP-17” badge

Pro tip: Damus shows a lock icon with “NIP-17” text on secure messages.

Amethyst

Amethyst supports NIP-17 but may require explicit enablement:

1. Settings → Advanced → Protocol Settings
2. Enable “NIP-17 gift wrap for DMs”
3. The client will automatically negotiate NIP-17 with supported contacts

Note: Amethyst gracefully falls back to NIP-04 if the recipient doesn’t support NIP-17.

Primal

Primal has excellent NIP-17 support:

1. Settings → Security & Privacy
2. Under “Messaging Protocol” select “NIP-17 (Private)”
3. Optional: Enable “Auto-upgrade NIP-04 conversations” to convert existing chats

Security Best Practices

Maximize your privacy when using NIP-17:

1. Verify Client Support Before Sensitive Communication

Always confirm your contact uses a NIP-17-capable client before sharing sensitive information. Sending NIP-17 to a NIP-04-only client will result in unreadable messages.

2. Don’t Mix Protocols in Same Thread

Avoid confusion by using one protocol per conversation. If you start with NIP-04, finish with NIP-04, or clearly indicate when switching.

3. Use Fresh Keys for High-Security Conversations

For maximum security:

• Create a dedicated keypair for sensitive communication
• Share the public key through a secure out-of-band channel
• Rotate keys periodically

4. Be Aware of Metadata in Other Event Types

NIP-17 only protects direct messages. Other event types (notes, reactions, follows) still expose social graph data. Use multiple identities for compartmentalization.

5. Choose Privacy-Focused Relays

Even with NIP-17, your traffic patterns are visible to relays. Use:

• Tor or VPN for additional network-level privacy
• Relays that don’t log or retain message metadata
• Multiple relays to distribute your traffic

6. Understand Limitations

NIP-17 provides excellent privacy but is not perfect:

• Relays can still see IP addresses (use VPN/Tor)
• Timing analysis can reveal communication patterns
• Compromised clients can leak information
• Recipient always sees sender identity

Troubleshooting Common Issues

”My messages never arrive” — check your DM relay list first

This is the most common NIP-17 failure, and it is almost never an encryption problem.

NIP-17 senders do not deliver to your normal relays. They look for a kind 10050 event — your published list of relays that accept your direct messages — and send the gift wrap only there. If you have never published one, a sender’s client has nowhere to deliver to, and the message is silently dropped. Nothing surfaces in either interface.

Fix: in a client that supports NIP-17, find the DM or private-messaging relay setting and save at least one relay. That publishes your kind 10050 list. Pick a relay that actually accepts gift wraps — some relays reject kind 1059 outright. (This is Step 3 of the migration guide — if you skipped it, start there.)

Keep the list short. Every relay you list is a relay that gets to see who is sending you messages.

”Messages show as unreadable or gibberish”

Cause: Recipient doesn’t support NIP-17 Solution: Ask recipient to update their client, or temporarily switch back to NIP-04

”Can’t see if someone read my NIP-17 message”

Cause: Read receipts not standardized for NIP-17 yet Solution: This is expected behavior. NIP-17 prioritizes privacy over delivery confirmation.

”Messages appear out of order”

Cause: Clock skew between devices Solution: Ensure your device time is synchronized (enable automatic time sync)

“Relay rejects NIP-17 events”

Cause: Old relay software Solution:

1. Check relay’s supported NIPs
2. Add modern relays that support NIP-17
3. Report to relay operator

”Client shows both NIP-04 and NIP-17 options”

Expected behavior: Many clients support both during transition period. Always choose NIP-17 when available.

The Future of Private Messaging in Nostr

NIP-17 is the current gold standard for Nostr private messaging, but development continues:

• NIP-44: An improved encryption scheme that may supersede NIP-17
• Group encryption: Private group messaging protocols are being developed
• Payment integration: Private messages with Lightning payments

Stay updated by following:

• nostr:npub1… # Nostr protocol development
• nostr:npub1… # Security best practices

Conclusion

NIP-17 represents a major step forward for privacy in Nostr. By addressing the metadata leakage problems of NIP-04, it enables truly private direct messaging that protects both content and communication patterns.

The migration process is straightforward: update your client, verify your contacts support NIP-17, and enjoy enhanced privacy. With widespread client support already available, there’s no reason to continue using the deprecated NIP-04 protocol.

Action items:

1. ✅ Update your Nostr client to the latest version
2. ✅ Enable NIP-17 in settings
3. ✅ Publish your DM relay list (kind 10050) — without it, nothing arrives
4. ✅ Verify with contacts that they support NIP-17
5. ✅ Start using NIP-17 for all new private conversations

Remember: Privacy is a practice, not a product. NIP-17 gives you the tools—use them wisely.

Test Your NIP-17 Knowledge

Ready to check your understanding of secure messaging?

Last updated: July 28, 2026

Have questions? Join the discussion on Nostr or open an issue on this documentation repository.

Keep reading

• Privacy and security on Nostr — the wider threat model these messages sit inside
• Your keys, your identity — losing the key loses the conversation, permanently