Skip to main content

LNURL Integration

Zapf natively implements the LUD-06 and LUD-16 protocols to seamlessly bridge traditional Lightning Network clients with the Nostr ecosystem.

LUD-16: Internet Identifiers​

LUD-16 allows Lightning wallets to resolve human-readable identifiers formatted like email addresses (e.g., user@example.com). Zapf leverages this to expose its entire identity graph to any standard lightning wallet.

When evaluating a LUD-16 identifier like discord:username#1234@zapf.app, the wallet makes a standard GET request:

GET https://zapf.app/.well-known/lnurlp/discord:username#1234

The Callback Response​

The IA intercepts this request, hashes the discord:username#1234 string, and searches the Nostr network for a valid, verified Kind 35521 connection.

It then responds with a standard LNURL payload:

{
  "callback": "https://zapf.app/api/lnurl/cb/discord:username#1234",
  "maxSendable": 100000000,
  "minSendable": 1000,
  "metadata": "[[\"text/identifier\",\"discord:username#1234@zapf.app\"]]",
  "tag": "payRequest",
  "commentAllowed": 255,
  "allowsNostr": true,
  "nostrPubkey": "<provider_pubkey>"
}

Key Zapf Extensions​

  • allowsNostr: true explicitly signals to NIP-57 capable clients that they can (and should) submit a Kind 5520 Zap Request to the callback URL.
  • The nostrPubkey provided is the IA's own pubkey, which the client will use to verify the resulting Kind 5521 Zap Receipt.

Invoice Generation (Callback)​

When the client accesses the callback URL (e.g., GET https://zapf.app/api/lnurl/cb/...&amount=10000&nostr=<url_encoded_kind_5520>), the IA executes the following logic:

  1. Validation: Validate the Kind 5520 against the requested amount.
  2. Target Resolution: Is the target a registered user with a connected NWC wallet?
    • Yes (Direct): The IA acts as a passthrough, retrieving an invoice directly from the user's NWC node.
    • No (Custodial): The IA generates an invoice from its own Master Node (The Fallback Address flow).
  3. Invoice Response: The IA returns the generated pr (payment request) to the client.
{
  "pr": "lnbc10n1...",
  "routes": []
}

Flokicon Chain Support​

If a user configures their profile to receive Flokicon instead of standard Bitcoin Lightning payments, the IA will inject Flokicon-specific routing hints into the LNURL response metadata and generate invoices conforming to the Flokicon network standards.