NIP-17: Private Direct Messages - A Complete Guide

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 signed with your real key, so the person you are writing to can tell the message is genuinely from you
2. Gift wrap (kind 1059), an outer envelope signed by a throwaway key. It hides the seal, so your real identity never appears on the event 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 that is nothing to do with your identity
• 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 closes most of that gap by wrapping the whole message in an outer envelope signed by a throwaway key, so the relay cannot tell who sent it. One thing stays in the open by design: the recipient’s public key rides on the envelope in a plain tag, because the relay has to know who to hand the message to. So NIP-17 hides the sender, not the recipient.

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 envelope a relay actually stores. Your client generates a brand new key for this one message, signs the envelope with it and throws the key away. The contents are encrypted so that only the recipient can open them. This layer carries:

• A random one-time public key, with nothing tying it back to you
• The recipient’s public key, in a plain tag the relay can read
• A randomised timestamp
• The sealed inner message

The Seal Layer (Inner)

Inside the gift wrap sits the seal. This is where authorship lives, and the relay never gets to see it. This layer:

• Is signed with your real key, which is how the recipient knows the message is yours
• Is encrypted with a key derived from your private key and the recipient’s public key, so only the two of you can read it
• Carries the message content
• Carries a timestamp that your client deliberately shifts backwards by up to two days, so nobody can group messages by when they were sent

Gift wrap (outer layer)

Random pubkey and a recipient hint, all a relay sees

Seal (inner layer)

Signed with the sender's real key, readable only by the recipient

Actual message content

Sender: real pubkey · Timestamp: 1234567890

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. Where it gets delivered is a third piece, the kind 10050 event. 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

NIP-17 only helps if the client at both ends of the conversation speaks it. These four say so in their own documentation or their own source code:

Damus needs a warning of its own. As of September 2026 the list of specifications Damus publishes still has no NIP-17 in it, only the old NIP-04. Two consequences, and both matter. A gift-wrapped message you send will not appear for someone on Damus at all. And anything they send you goes out as a plain kind 4 event with both of your public keys on the outside, where every relay that stores it can read them. If a conversation is sensitive, move it to one of the clients above.

Primal, Iris and Nos sit in an unsettled middle. Primal says nothing either way in public, so treat it as unknown. Iris encrypts its private chats with a double-ratchet scheme of its own rather than plain NIP-17, which is fine inside Iris and no guarantee of anything outside it. Nos lists neither NIP-17 nor the two specifications it is built on, and the project has been quiet since early 2025.

Client feature lists move faster than guides do. If yours is not named here, the test in Step 5 settles it faster than reading changelogs.

Step 2: There Is Usually Nothing to Switch On

This step is shorter than you would expect. None of the clients above document a “turn on NIP-17” toggle, because there isn’t one to find. They use gift wraps automatically the moment the person on the other end can receive them.

So skip ahead to Step 3, which is the part that actually needs you. Your existing NIP-04 conversations stay where they are and stay readable; nothing converts them.

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 for you the first time you open a private chat. Don’t assume yours did: 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:

"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 It Actually Works

The check that matters needs no technical skill at all. Ask someone using one of the clients from Step 1 to message you, then reply. If both directions arrive, your kind 10050 list is published and gift wraps are reaching you. If your message vanishes and neither of you sees an error, that is the classic missing-relay-list symptom, and Step 3 is where to go back to.

You can run the same test alone: log into your account on a second client, or message yourself if your client allows it.

If you are curious about what is really being sent, a Nostr event viewer such as njump.me will show you raw events. A working gift wrap looks roughly like this:

// 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>"
}

Two things to read there. The pubkey is a one-time key you will not recognise, and that is the sender being hidden, exactly what you want. The p tag does show the recipient’s real key. That is not a fault in your setup; the relay needs it to know where the message goes.

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 anything sensitive. A gift wrap sent to someone whose client only speaks NIP-04 does not arrive as gibberish. It does not arrive at all: their client never goes looking for kind 1059 events, and neither of you gets an error.

2. Treat Dropping Back to NIP-04 as a Real Decision

Some clients will let you keep an old NIP-04 thread going. That is occasionally the practical choice, but know what it costs: a NIP-04 message puts both public keys, in the clear, on an event every relay stores. Keep it for chat you would not mind being publicly linked to you, and start anything sensitive as a fresh NIP-17 conversation instead.

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 is a real improvement, and it is not a cloak:

• Relays still see your IP address (use a VPN or Tor)
• Timing analysis can still reveal communication patterns
• The recipient’s key is on the envelope in plain text, by design
• A compromised phone or client leaks everything, whatever the protocol does

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, because 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.

”One particular contact never gets anything I send”

If everyone else hears from you and one person doesn’t, the problem is at their end, not in your encryption. Their client almost certainly has no NIP-17 support, so it never subscribes to gift wraps and never sees your message. Nothing shows up as gibberish, because nothing shows up at all.

Fix: ask them to move to a client from Step 1. If they can’t, and the two of you can only talk over old NIP-04 messages, read the warning in Security Best Practices first: NIP-04 hands both of your public keys to every relay in the clear.

”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: the relay is running old software, or it simply refuses to store kind 1059 events Solution: swap it out of your DM relay list for a different one. Some clients show what a relay supports on its relay screen; if yours doesn’t, trying another relay and seeing whether messages start arriving is quicker than investigating. Telling the operator is worth a minute too.

”My client offers me a choice of message type”

Expected behaviour: some clients still read and write both formats while the network finishes moving over, and let you pick per conversation. Choose NIP-17 whenever it is on offer.

The Future of Private Messaging in Nostr

NIP-17 is the current standard for one-to-one private messaging on Nostr, and it is what you should be using today. It is not the end of the road, though, and its two real gaps are the ones people are working on: no forward secrecy, and no proper group chat.

The most serious answer so far is the Marmot protocol, which puts MLS (the group-messaging standard behind Signal-style group chat) on top of Nostr, keeping Nostr keys as identity. Marmot’s own repository lists the spec as adopted, and White Noise is the chat app built on it. That approach does give forward secrecy and does handle groups, which is exactly what NIP-17 leaves out.

One clarification, because the numbers invite it. NIP-44 is not a competitor to NIP-17 and will not replace it. NIP-44 is the encryption NIP-17 already uses for both of its layers. They are parts of the same thing.

Conclusion

NIP-17 is a real improvement on NIP-04, and it is what you should be using. Be clear about what you are getting, though. Your words are encrypted and the relay cannot tell who sent a message. It can still see which account the message is for, and anyone watching both ends can still learn a lot from timing. Treat it as private mail rather than an untraceable one.

Moving over is mostly a matter of picking the right client and publishing one small list. Support is real but uneven, and Damus, one of the most-used clients on iPhone, still has none, so checking the other end of a conversation is not an optional step.

Action items:

1. ✅ Use a client that supports NIP-17 (Amethyst, 0xchat, Coracle, Snort)
2. ✅ Publish your DM relay list (kind 10050). Without it, nothing arrives
3. ✅ Send a test message both ways with a contact, so you know delivery works
4. ✅ Before anything sensitive, check which client the other person is on

Remember: privacy is a practice, not a product. NIP-17 gives you the tools; using them well is still up to you.

---

Test Your NIP-17 Knowledge

Ready to check your understanding of secure messaging?

NIP-17 Private Messages Quiz

NIP-17 Purpose

Question 1 of 5

0/5 answered

What is NIP-17?

A new type of relay

An improved encryption standard for private messages replacing NIP-04

A Bitcoin wallet integration

---

Last updated: September 2, 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, because losing the key loses the conversation, permanently