Why Integrate Satograms#

The opportunity#

Satograms are message-attached sats that get broadcast to many lightning-address recipients in a single campaign. Senders pay upfront; the service fans the payment out across the Lightning Network. If your users have lightning addresses on your domain (e.g. alice@yourwallet.com), they will already receive Satograms through the LNURL-pay flow you have today, no integration on your part beyond what LUD-12 already requires. Integration unlocks two things: (1) display the sender’s message to your user, turning a “5 sats received” notification into “Bob sent you 5 sats with this note”, and (2) if your volume justifies it, opting into the batch keysend path which lets you take an explicit cut of every Satogram destined for your users.

What’s in it for you#

1. The cut (batch keysend mode)#

This is the headline number. When you opt into batch keysends:

• The Satogram service sends one keysend to your node that covers N of your users at once.
• The keysend’s amount_msat is N × per_satogram_amount × 1000.
• You decide how much of that you credit to users and how much you keep as a delivery fee. The protocol does not enforce a split. There is no operator-side share.

A worked example. A Satogram campaign at 5 sats per recipient hits 10,000 lightning addresses across the network. 1,200 of those are on your wallet:

Multiply by campaigns per month and the cut compounds. The cut works for one specific reason: Satograms are unsolicited inbound messages, not user-requested payments. Charging a delivery fee on incoming-spam-with-sats is a legitimately better revenue source than charging your users on payments they explicitly accepted.

Your rate is set per-wallet during onboarding with the operator. The example code in this guide leaves the rate as a configurable constant; replace it with the rate from your operator agreement.

2. Free inbound activity for your users#

Every Satogram campaign hits every known lightning address on the network. If you have N users with addresses on your domain, you receive N inbound payments per campaign with zero marketing spend. Users see activity in their wallets. Engagement goes up. Inbound activity is one of the strongest retention signals in any consumer fintech.

3. Stickier lightning addresses#

Lightning addresses are sticky identities, a user with alice@yourwallet.com has a reason to keep the handle live, which means keeping the account live. Inbound Satograms reinforce this: the more sats land in their handle, the higher the switching cost.

4. Brand listing#

The Satogram service maintains internal lists of supported wallets. Being on that list is free distribution. Senders see your domain in their UI; recipients see “delivered to your wallet” in their notifications.

What does it cost?#

Honest accounting:

• Engineering effort: roughly 1-3 dev-days for Path A (LNURL-pay configuration check + reading two TLVs off settled invoices). Add 2-5 more dev-days for Path B (batch keysend acceptance + recipient-list parsing + accounting policy for the cut).
• Inbound liquidity: for batch keysends you receive in chunks of up to 50 × per_satogram sats per payment. At 5 sats per recipient that’s 250 sats per HTLC, trivial. For most providers this volume is well below normal channel-capacity headroom; you don’t need to provision specifically for Satograms.
• Routing fees: zero. You’re the receiver.
• Ongoing ops: your existing invoice subscriber plus ~50 lines of TLV-parsing code. No new infrastructure.
• Integration fee / token / escrow: none beyond the negotiated per-Satogram delivery fee. Opt-in is a one-line config change on the operator’s side (your domain + node pubkey added to their opt-in list).

Who’s already integrated?#

A leading Lightning custodial wallet is already live on the batch keysend path; the design was built around their integration pattern. Adopting this pattern means following a well-trodden path, not pioneering.

What you’re agreeing to (and what you’re not)#

What you’re agreeing to:

• Crediting users who appear in TLV 6789998212 of an incoming Satogram payment, on a reasonable best-effort basis.
• Keeping commentAllowed > 0 on your LNURL-pay endpoint so per-recipient delivery works.
• If opting into batch keysend: keeping accept-keysend=true (LND default) and your node reachable.

What you’re not agreeing to:

• No SLA. If your node is down, the operator’s service tolerates the failures and moves on.
• No mandated fee rate. Your cut is your business decision.
• No mandated UX. How you surface the message to users (notification, transaction history, in-app message inbox) is up to you.

How to get started#

1. Read How it works for the technical model. 10-minute read.
2. Verify your LNURL-pay endpoint meets the requirements. For many wallets this is a one-line config bump on commentAllowed.
3. Add TLV reading to your existing invoice subscriber: Detecting payments.
4. Test on regtest: Testing.
5. If you want the cut: Opt into batch keysends.

Realistic timeline from kickoff to first Satogram credited in production: 1-2 weeks.