← Back to Wallet Providers

Batch Keysend Opt-In#

Opting your wallet into batch keysend mode is what unlocks the custodial cut described in Why integrate. This doc covers what changes operationally and how to onboard.

What it does#

Without opt-in, the Satogram service pays your users one-by-one through your LNURL-pay endpoint. You receive one inbound payment per user per campaign.

With opt-in, the service bundles up to 50 of your users into a single keysend to your node, with the recipient list packed into TLV 6789998212 as comma-separated lightning addresses. You credit each user from the recipient list and keep the remainder as your fee.

The protocol does not enforce a fee split. Your rate is set per-wallet during onboarding with the operator. The example code in this guide leaves the fee as a configurable constant; replace it with your negotiated rate.

Technical requirements#

Before requesting opt-in, confirm:

Requirement Why
Your node accepts keysend payments LND: accept-keysend=true in lnd.conf (this is the default but verify). CLN: keysend plugin loaded (default). LDK: keysend feature bit signaled. Eclair: eclair.features.keysend = optional.
Your subscriber reads TLV 6789998212 and splits on , The same code path handles single-address (Path A) and CSV (Path B). See Detecting payments.
Your subscriber tolerates unknown recipients in the CSV A batch may include an address that doesn’t exist in your user table (a recently-deleted user, a typo, etc.). Your code must drop those credits, not throw. See test (3) in Testing.
You have a documented policy for the unknown-recipient case Refund the operator? Drop the sats? Park them in an operator-bucket account? Pick one and write it down.
Your node has enough inbound liquidity headroom Each batch HTLC is at most 50 × per_satogram sats. At 5 sats per recipient that’s 250 sats per HTLC, well within normal channel capacity. The volume question is “how many batches per day”, usually well below any threshold you’d need to provision for.

Minimums#

The Satogram service enforces a minimum payment of 10 sats when paying lightning-address-style recipients in a batch. Below 10 sats the batch rounds up to 10. This means:

  • If your wallet credits with sat precision: you’ll receive at least 10 sats per recipient in a batch and credit at least 10 - fee_cut sats. (For example, a small fee leaves a single-digit-sat credit per recipient.)
  • If your wallet has a higher credit floor (e.g. 100 sats): your policy choices are (a) skip recipients whose per-recipient share is below your floor and keep the dust as additional fee, or (b) accumulate sub-floor credits until they cross the floor.

Onboarding steps#

The operator maintains the opt-in list of supported wallets internally. To get added, send the Satogram operator:

  1. Your wallet’s domain. Example: yourwallet.com. This is the suffix the service uses to match lightning addresses to your domain.
  2. The LND/CLN/LDK/Eclair node pubkey that should receive batched keysends. Use a node with healthy inbound liquidity from the operator’s node, or peer with them directly so you don’t depend on third-party routing for high-volume delivery.
  3. Confirmation that your invoice subscriber handles TLV 6789998212 as a comma-separated list and credits recipients individually.
  4. Confirmation that you accept keysends on the configured node.
  5. Your unknown-recipient policy (refund / drop / operator-bucket) so the operator knows what to expect if a campaign references a stale user.
  6. (Optional) Your fee rate, if you want it documented somewhere. The operator doesn’t need this to enable opt-in, but some integrators prefer to publish it.

There is no commercial agreement, integration fee, or SLA. The operator adds your row to the config and the next campaign starts batching to you.

Reverting opt-in#

To stop receiving batches, ask the operator to remove your row. Your users continue receiving Satograms via the LNURL-pay path. Nothing else changes on your side; your subscriber should already handle Path A.

What about routing fees and capacity?#

You’re receiving, so routing fees are paid by the sender. The relevant capacity question is inbound: can the operator’s node push you N × per_satogram sats in a single HTLC?

For typical campaigns (per_satogram=5 sats, batches up to 50 recipients), each HTLC is up to 250 sats. This is a small amount and routes easily through almost any path. The only failure mode worth thinking about is if every channel between the operator’s node and yours has insufficient remote-side balance at HTLC time, in which case the batch falls back to per-recipient LNURL-pay payments for that campaign. No data is lost; users still get credited via Path A.

For high-volume providers, peering directly with the operator’s node is the way to make this entirely deterministic.