Keysend

What Is Keysend?

Keysend is a Lightning Network feature that allows sending payments to a node without first requesting an invoice. In standard Lightning payments, the recipient creates an invoice that includes a payment hash, and only the recipient knows the preimage that unlocks the payment. Keysend flips this model: the sender generates both the payment hash and preimage, then sends the preimage to the receiver inside the encrypted onion payload.

The name "keysend" reflects the core mechanism: you send the key (preimage) along with the payment. The receiver uses this key to claim the funds. Because the preimage travels inside onion encryption, only the final recipient can read it and complete the payment.

Keysend was originally implemented in LND as an experimental feature and has since been adopted across major Lightning implementations. While not part of the core BOLT specifications, it has become a de facto standard for spontaneous payments.

How Keysend Works

Understanding keysend requires knowing how standard Lightning payments work. In a normal payment:

1. Receiver generates preimage: The recipient creates a random 32-byte preimage and calculates its SHA256 hash.
2. Receiver creates invoice: The invoice includes the payment hash (but not the preimage), amount, and expiry.
3. Sender routes HTLC: The sender creates an HTLC locked to the payment hash and routes it through the network.
4. Receiver reveals preimage: The recipient reveals the preimage to claim the HTLC, and this preimage propagates back to the sender as proof of payment.

Keysend modifies this flow:

1. Sender generates preimage: The sender creates a random 32-byte preimage and calculates the payment hash.
2. Sender includes preimage in onion: The preimage is added to the final hop payload using TLV (Type-Length-Value) record type 5482373484. This data is encrypted in the onion, visible only to the final recipient.
3. Sender routes HTLC: The payment routes normally through the network, locked to the payment hash.
4. Receiver extracts and uses preimage: The recipient decrypts the onion, extracts the preimage, verifies it matches the payment hash, and uses it to claim the HTLC.

The critical insight is that intermediate routing nodes only see the payment hash in the HTLC. They cannot access the preimage hidden in the onion payload. Only the final recipient, who can fully decrypt the onion, learns the preimage.

Keysend vs Traditional Invoices

Both keysend and invoice-based payments result in completed Lightning transactions, but they serve different use cases and have distinct security properties.

Invoice-Based Payments

• Receiver controls preimage: Only the receiver knows the preimage, providing cryptographic proof that payment was intentional.
• Request-response flow: Requires communication between parties before payment can occur.
• Amount specification: Invoices typically specify exact amounts, reducing overpayment errors.
• Expiry and metadata: Invoices can include descriptions, expiry times, and route hints.

Keysend Payments

• Sender controls preimage: The sender generates the preimage, which the receiver must trust.
• Push-only flow: No prior communication needed. Send to any node whose public key you know.
• Flexible amounts: Sender decides the amount without receiver input.
• Minimal metadata: Basic keysend has no built-in description field, though custom TLV records can add metadata.

When to Use Each

Use invoices for commerce, defined payments, and situations requiring explicit payment requests. Invoices provide clear receipts and the receiver maintains control over payment acceptance.

Use keysend for tips, donations, streaming payments, and cases where generating an invoice per payment is impractical. Keysend excels in push-payment scenarios where the receiver passively accepts funds.

Use Cases

Streaming Sats (Podcasting 2.0)

The most prominent keysend application is streaming payments for podcast listeners. In the Podcasting 2.0 ecosystem, listeners can stream satoshis to creators in real-time as they listen. A podcast player might send 100 sats per minute of playback directly to the creator's node.

Invoices would be impractical here. Generating and paying an invoice every minute (or more frequently) would create massive overhead. Keysend enables continuous micropayment streams where each payment is independent and requires no back-and-forth communication.

Tips and Donations

Content creators, open source developers, and anyone accepting Lightning tips benefit from keysend. A viewer can send a tip to a creator's node without the creator needing to generate a unique invoice. The creator simply publishes their node public key, and supporters send funds at will.

This is particularly useful for asynchronous tipping. A blog post might include a node pubkey, and readers can tip days or weeks later without any real-time interaction.

Circular Rebalancing

Node operators use keysend for internal channel rebalancing. You can send a payment from your node back to yourself through a circular route, shifting liquidity between channels. Since you control both ends, invoice generation is unnecessary overhead.

Automated Payments

Systems that need to send programmatic payments benefit from keysend. A bot distributing rewards, a service paying out earnings, or an automated split payment system can all use keysend to push funds without managing invoice generation and expiry.

Technical Implementation

Keysend uses TLV (Type-Length-Value) extension records in the onion payload. The preimage is transmitted using TLV type 5482373484.

LND Implementation

In LND, keysend must be explicitly enabled. Once active, you can send keysend payments using the sendpayment command:

# Enable keysend in lnd.conf
accept-keysend=true

# Send a keysend payment
lncli sendpayment --dest <pubkey> --amt 1000 --keysend

# Send with a custom message using TLV
lncli sendpayment --dest <pubkey> --amt 1000 --keysend \
  --data 34349334=<hex_encoded_message>

Core Lightning Implementation

Core Lightning supports keysend through the keysend plugin:

# Send keysend payment
lightning-cli keysend <destination_pubkey> <amount_msat>

# With a message
lightning-cli keysend <destination_pubkey> <amount_msat> \
  extratlvs={34349334: <hex_message>}

TLV Records

Keysend payments often include additional TLV records for metadata. Common types include:

• 5482373484: The keysend preimage (required)
• 34349334: Text message attached to payment
• 7629169: Podcast episode GUID
• 7629175: Timestamp within podcast episode

The Podcasting 2.0 specification defines additional TLV types for attribution, splits, and streaming metadata.

Limitations and Security Considerations

Preimage Trust Model

The fundamental security difference with keysend is preimage generation. In invoice-based payments, the receiver generates the preimage and can guarantee its uniqueness. With keysend, the receiver must trust that the sender generated a unique, random preimage.

A malicious sender could theoretically reuse preimages, though this primarily affects their own proof-of-payment guarantees rather than the receiver's funds. Once the receiver claims the HTLC using the provided preimage, the payment is complete regardless of whether that preimage was used before.

No Native Receipt

Keysend payments lack the structured receipt that invoices provide. There is no description field, no specified amount expectation, and no expiry. Receivers may struggle to attribute incoming keysend payments to specific senders or purposes without additional TLV metadata.

Must Know Recipient Pubkey

Keysend requires knowing the recipient's node public key. This is less user-friendly than scanning a QR code invoice. Recipients need to publish and maintain their pubkey, and senders need additional context about who they are paying.

Spam Potential

Because anyone can send to a known pubkey without permission, keysend opens nodes to unsolicited payments. While receiving money is generally positive, high volumes of dust payments could create operational issues. Most implementations let operators disable keysend if needed.

Not in BOLT Specification

Keysend is not formally specified in the BOLT documents. It emerged from LND as an experimental feature and spread through adoption rather than standardization. This means implementations may have subtle differences, though core functionality is consistent.

FAQ