Nostr.Event.ZapRequest (Nostr Lib v0.2.1) (event) (nip57)

View Source

Zap Request events (Kind 9734).

Implements NIP-57: https://github.com/nostr-protocol/nips/blob/master/57.md

A zap request is NOT published to relays. Instead, it is sent to the recipient's LNURL pay callback URL to request a Lightning invoice. When the invoice is paid, the recipient's wallet publishes a zap receipt (kind 9735).

Required Tags

  • relays - list of relays where the receipt should be published
  • p - recipient's pubkey (exactly one)

Optional Tags

  • amount - amount in millisatoshis
  • lnurl - bech32-encoded lnurl
  • e - event being zapped (0 or 1)
  • a - addressable event coordinate
  • k - kind of the zapped event

Examples

# Create a zap request for a user
ZapRequest.create("recipient_pubkey", ["wss://relay.example.com"],
  amount_sats: 1000,
  message: "Great post!"
)

# Create a zap request for an event
ZapRequest.create("recipient_pubkey", ["wss://relay.example.com"],
  amount_sats: 100,
  event_id: "event_id_to_zap",
  kind: 1
)

Summary

Types

t()

Functions

create(recipient, relays, opts \\ [])

Creates a zap request event.

parse(event)

Parses a kind 9734 event into a ZapRequest struct.

to_callback_url(zap_request, callback_url)

Builds the LNURL callback URL with the zap request as a query parameter.

Types

t()

@type t() :: %Nostr.Event.ZapRequest{
  address: binary() | nil,
  amount_msats: non_neg_integer() | nil,
  event: Nostr.Event.t(),
  event_id: binary() | nil,
  kind: non_neg_integer() | nil,
  lnurl: binary() | nil,
  message: binary(),
  recipient: binary(),
  relays: [binary()]
}

Functions

create(recipient, relays, opts \\ [])

@spec create(binary(), [binary()], keyword()) :: t()

Creates a zap request event.

Options

  • :amount_sats - amount in satoshis (will be converted to millisats)
  • :amount_msats - amount in millisatoshis (takes precedence over amount_sats)
  • :lnurl - bech32-encoded lnurl of recipient
  • :event_id - event ID being zapped
  • :address - addressable event coordinate (e.g., "30023:pubkey:identifier")
  • :kind - kind of the event being zapped
  • :message - optional message/comment

Examples

ZapRequest.create("pubkey", ["wss://relay.example.com"],
  amount_sats: 1000,
  event_id: "abc123",
  kind: 1,
  message: "Great post!"
)

parse(event)

@spec parse(Nostr.Event.t()) :: t() | {:error, String.t(), Nostr.Event.t()}

Parses a kind 9734 event into a ZapRequest struct.

Validation

Per NIP-57 Appendix D:

  • Must have exactly one p tag
  • Must have 0 or 1 e tags
  • Must have 0 or 1 a tags

to_callback_url(zap_request, callback_url)

@spec to_callback_url(t(), binary()) :: binary()

Builds the LNURL callback URL with the zap request as a query parameter.

The zap request event must be signed before calling this function.

Example

signed_request = Event.sign(zap_request.event, seckey)
url = ZapRequest.to_callback_url(%{zap_request | event: signed_request}, callback_url)
# => "https://lnurl.example.com/callback?amount=1000&nostr=..."