Nostr Zap Integration

Overview

Build correct Lightning Zap and Nutzap flows for Nostr applications. This skill covers the full NIP-57 lifecycle (LNURL discovery, zap request construction, invoice handling, zap receipt validation) and the NIP-61 Cashu alternative (nutzap configuration, P2PK token minting, nutzap publishing and redemption).

When to Use

• Implementing "zap" functionality in a Nostr client
• Constructing kind:9734 zap request events
• Validating kind:9735 zap receipt events
• Integrating LNURL-pay endpoints with Nostr
• Building zap split support for events with multiple

  zap

  tags
• Implementing NIP-61 Nutzaps (Cashu-based zaps)
• Setting up kind:10019 nutzap receiving configuration
• Constructing kind:9321 nutzap events with P2PK-locked tokens
• Debugging zap flows (missing tags, validation failures, amount mismatches)

Do NOT use when:

• Building general Lightning/LNURL wallets unrelated to Nostr
• Implementing relay WebSocket protocol logic
• Working with NIP-19 bech32 encoding (separate concern)
• Building Cashu wallets without Nostr integration

Workflow

1. Determine the Payment Path

Ask: "Is this a Lightning Zap (NIP-57) or a Nutzap (NIP-61)?"

If unsure, check the recipient's profile (kind:0) for

lud16

lud06

2. Lightning Zap Flow (NIP-57)

Follow the steps in references/zap-flow.md for the complete implementation. Summary:

Step 2a: Discover the LNURL Endpoint

// From lud16 (e.g., "bob@example.com")
const [name, domain] = lud16.split("@");
const url = `https://${domain}/.well-known/lnurlp/${name}`;
const res = await fetch(url);
const lnurlPayData = await res.json();

// Verify Nostr support
if (!lnurlPayData.allowsNostr || !lnurlPayData.nostrPubkey) {
  throw new Error("Recipient does not support Nostr zaps");
}

Critical checks on the LNURL response:

• allowsNostr

  MUST be

  true

• nostrPubkey

  MUST be a valid 32-byte hex public key
• Save

  callback

  ,

  minSendable

  ,

  maxSendable

  for later use

Step 2b: Construct the Zap Request (kind:9734)

{
  "kind": 9734,
  "content": "Optional zap comment",
  "tags": [
    ["relays", "wss://relay1.example.com", "wss://relay2.example.com"],
    ["amount", "21000"],
    ["lnurl", "lnurl1dp68gurn8ghj7..."],
    ["p", "<recipient-pubkey-hex>"],
    ["e", "<event-id-hex>"],
    ["k", "<event-kind-string>"]
  ]
}

Required tags:

relays

p

amount

lnurl

e

a

k

Critical: The zap request is NOT published to relays. It is sent to the LNURL callback URL.

Step 2c: Send to Callback and Get Invoice

const zapRequestEncoded = encodeURIComponent(JSON.stringify(signedZapRequest));
const url =
  `${callback}?amount=${amountMsats}&nostr=${zapRequestEncoded}&lnurl=${lnurlBech32}`;
const { pr: invoice } = await fetch(url).then((r) => r.json());

Step 2d: Pay the Invoice

Pass the bolt11 invoice to a Lightning wallet for payment. After payment, the recipient's LNURL server creates and publishes the zap receipt (kind:9735).

Step 2e: Validate Zap Receipts

See references/zap-flow.md for full validation logic. The three critical checks:

1. Receipt

   pubkey

   MUST match the recipient's LNURL

   nostrPubkey

2. Invoice amount in

   bolt11

   tag MUST match

   amount

   in the zap request

3. SHA256(description)

   SHOULD match the bolt11 description hash

3. Nutzap Flow (NIP-61)

Follow the steps in references/nutzap-flow.md for the complete implementation. Summary:

Step 3a: Fetch Recipient's Nutzap Configuration (kind:10019)

{
  "kind": 10019,
  "tags": [
    ["relay", "wss://relay1.example.com"],
    ["relay", "wss://relay2.example.com"],
    ["mint", "https://mint.example.com", "sat"],
    ["mint", "https://othermint.example.com", "usd", "sat"],
    ["pubkey", "<p2pk-pubkey-hex>"]
  ]
}

Critical: The

pubkey

Step 3b: Mint P2PK-Locked Tokens

1. Choose a mint from the recipient's

   mint

   tags
2. Mint or swap tokens P2PK-locked to the recipient's

   pubkey

   value
3. Prefix the pubkey with

   "02"

   for nostr-cashu compatibility
4. Include DLEQ proofs (NUT-12)

Step 3c: Publish the Nutzap (kind:9321)

{
  "kind": 9321,
  "content": "Optional comment",
  "tags": [
    ["proof", "<cashu-proof-json>"],
    ["unit", "sat"],
    ["u", "https://mint.example.com"],
    ["e", "<zapped-event-id>", "<relay-hint>"],
    ["k", "<zapped-event-kind>"],
    ["p", "<recipient-nostr-pubkey>"]
  ]
}

Publish to the relays listed in the recipient's kind:10019

relay

Step 3d: Receiving Nutzaps

Recipients query for kind:9321 events p-tagging them, filtered by trusted mint URLs (

#u

4. Zap Splits

When an event has

zap

["zap", "<pubkey>", "<relay>", "<weight>"]

Weights are relative. Calculate percentages:

const totalWeight = zapTags.reduce((sum, t) => sum + Number(t[3] || 0), 0);
for (const tag of zapTags) {
  const weight = Number(tag[3] || 0);
  const pct = weight / totalWeight;
  const recipientAmount = Math.floor(totalAmount * pct);
  // Create separate zap request for each recipient
}

Recipients without a weight value get weight 0 (no zap). If no weights are present on any tag, divide equally.

Checklist

• Identified payment path (Lightning vs Nutzap)
• For Lightning: LNURL endpoint discovered and verified (

  allowsNostr

  ,

  nostrPubkey

  )
• For Lightning: Zap request (kind:9734) has required tags (

  relays

  ,

  p

  )
• For Lightning: Zap request sent to callback URL, NOT published to relays
• For Lightning: Amount in millisats, within

  minSendable

  /

  maxSendable

• For Lightning: Zap receipt validation checks all three criteria
• For Nutzap: Recipient's kind:10019 fetched and parsed
• For Nutzap: Tokens minted at one of recipient's listed mints
• For Nutzap: P2PK pubkey prefixed with "02" and is NOT the main Nostr key
• For Nutzap: kind:9321 published to recipient's specified relays
• For splits: Weights calculated correctly, separate zap per recipient

Common Mistakes

amount

pubkey

relays

relays

nostrPubkey

mint

allowsNostr

allowsNostr: true

Quick Reference

relays

p

amount

lnurl

e

p

P

bolt11

description

e

relay

mint

pubkey

proof

u

unit

p

e

e

p

Key Principles

1. Zap requests are HTTP-only — Kind:9734 events are NEVER published to relays. They are signed, JSON-encoded, URI-encoded, and sent as a query parameter to the LNURL callback URL. This is the most common mistake.

2. Validate the full chain — A valid zap receipt requires matching the receipt pubkey to the LNURL

   nostrPubkey

   , matching the invoice amount to the request amount, and verifying the description hash. Skipping any check allows forged zaps.

3. Nutzap keys are separate — The P2PK pubkey in kind:10019 MUST be a different key from the user's main Nostr identity key. Using the same key would allow anyone to spend received tokens. Always prefix with "02".

4. Amounts are in millisatoshis — NIP-57 uses millisats everywhere (1 sat = 1000 msats). The

   amount

   tag,

   minSendable

   ,

   maxSendable

   , and invoice amounts are all in millisats.

5. Trust boundaries matter — Zap receipts are NOT cryptographic proofs of payment. They prove that a LNURL server claims payment was received. The trust is in the LNURL server operator, not in the protocol itself.