← All NIPs

NIP-40

Expiration Timestamp

DraftEventsRelay

Adds an expiration tag so an event can say when it stops being relevant. Supporting relays stop serving it after that moment and clients hide it, which suits temporary announcements and time-limited offers.

Status
In use and still allowed to change.
Tags
  • expiration
Last changed
Dec 23, 2025

Try it

Edit the form or the JSON: both stay in sync, the badge says whether the result is valid, and tapping any field explains it.

Examples
Valid 1 note

Not signed yet · Demo keys only. These personas' secret keys are public on purpose.

Form
Jan 1, 2025, 12:00 AM UTC

Content

Whatever the event kind normally holds. NIP-40 only adds the tag; the content is unaffected.

Tags

  1. expiration Required

    Marks the moment after which relays and clients should treat the event as expired. Only one per event.

    Jan 2, 2025, 12:00 AM UTC
Add tag

How this NIP works

Step 1 of 5

Add the expiration tag

The author picks a future Unix timestamp and adds ["expiration", "<timestamp>"] before signing. The tag is covered by the signature, so nobody can move the date later.

In the course

No course chapter covers this NIP yet. The editor above is the quickest way in.

Builds on

Extends

Used by

See also

Specification

Specification text is quoted in English from the nostr-protocol/nips repository. Our explanations and the interface are translated. Source on GitHub at commit 0046368

Read the spec316 words, quoted from the repository at commit 0046368.

The expiration tag enables users to specify a unix timestamp at which the message SHOULD be considered expired (by relays and clients) and SHOULD be deleted by relays.

Spec
tag: expiration
values:
 - [UNIX timestamp in seconds]: required
Example
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 1,
  "tags": [
    ["expiration", "1600000000"]
  ],
  "content": "This message will expire at the specified timestamp and be deleted by relays.\n",
  "id": "<event-id>"
}

Note: The timestamp should be in the same format as the created_at timestamp and should be interpreted as the time at which the message should be deleted by relays.

Client Behavior

Clients SHOULD use the supported_nips field to learn if a relay supports this NIP. Clients SHOULD NOT send expiration events to relays that do not support this NIP.

Clients SHOULD ignore events that have expired.

Relay Behavior

Relays MAY NOT delete expired messages immediately on expiration and MAY persist them indefinitely. Relays SHOULD NOT send expired events to clients, even if they are stored. Relays SHOULD drop any events that are published to them if they are expired. An expiration timestamp does not affect storage of ephemeral events.

Suggested Use Cases

  • Temporary announcements - This tag can be used to make temporary announcements. For example, an event organizer could use this tag to post announcements about an upcoming event.
  • Limited-time offers - This tag can be used by businesses to make limited-time offers that expire after a certain amount of time. For example, a business could use this tag to make a special offer that is only available for a limited time.
Warning

The events could be downloaded by third parties as they are publicly accessible all the time on the relays. So don't consider expiring messages as a security feature for your conversations or other uses.