Skip to main content

The Fallback Address

Lightning Network payments are push-based. Traditionally, the recipient must generate an invoice before a payment can occur. If the recipient doesn't have a wallet—or their node is temporarily offline—the sender's payment fails.

The Fallback Address solves this friction. It guarantees that payments never fail, safely holding funds in a temporary escrow until the recipient is ready to claim them.

For Users: How Your Funds Stay Safe​

You don't need a Lightning wallet to start receiving zaps. If someone sends you value across the network, the Fallback Address automatically catches it.

The Experience​

  1. Safe Escrow: A trusted Zap Settlement Provider (ZSP) receives the funds and places them in a secure temporary hold on your behalf.
  2. Verifiable Proof: The ZSP publishes a public cryptographic receipt, proving to the sender that the payment succeeded.
  3. The Claim Flow: Whenever you are ready, you connect your personal wallet (via Nostr Wallet Connect). The ZSP instantly and automatically sweeps all pending funds to your personal balance.

Once your wallet is connected, the Fallback Address retires. All future payments will settle natively and directly into your own wallet.

Receiving Limits & Provider Policies​

Because the Zap Settlement Provider temporarily holds these funds on its own Lightning nodes, they must manage channel liquidity. To ensure system stability, individual ZSPs typically enforce daily or monthly caps on how much volume a Fallback Address can receive.

If you anticipate receiving significant volume—or want to bypass these limits entirely—we strongly recommend connecting your own native Lightning wallet. Always review your specific ZSP's terms of service regarding escrow limits.

For Developers: Implementing the Fallback Flow​

The Fallback mechanism allows your application to support identity-based payments for users who haven't fully onboarded yet, removing the risk of failed payments hurting your UX.

Triggering the Fallback (pubkey@zsp_domain)​

When your frontend application resolves a user's identity but discovers they lack a valid lud16 (native Lightning Address), you must construct an LNURL pointing to the ZSP's fallback handler.

The format strictly expects the recipient's 64-character hex Nostr public key, joined with the ZSP's domain.

// Example: Constructing the Fallback LNURL Address
const fallbackAddr = `${pubkey}@zapf.app`; 
// Result: a1b2c3...f8e9@zapf.app

This deterministic format ensures the ZSP knows exactly who the funds belong to when creating the pending balance. (Note: Do not use npub bech32 formats; the backend resolver exclusively requires hex).

Behind the Scenes: The ZSP Lifecycle​

When a payment is sent to a pubkey@zsp_domain address, the ZSP manages the transaction state:

  1. Internal Settlement: The ZSP generates an invoice from its own Master Node and settles the payment internally into a custodial ledger.
  2. Cryptographic Proof: The ZSP publishes a Zap Receipt (Kind 5521), providing finality to the sender and an immutable record of the pending liability.
  3. Resolution: To retrieve their funds, the recipient completes an OAuth flow (e.g., Discord) and publishes an Identity Connection (Kind 35521).
  4. The Sweep: The ZSP detects the new 35521 event, verifies the signature ownership, and automatically sweeps the Escrow balance to the user's newly designated node.