← 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 delivery fee rate is set during onboarding. The example code leaves it as a placeholder constant for you to replace.

Technical requirements#

Before requesting opt-in, confirm:

Requirement Why
Your node accepts keysend payments LND: set accept-keysend=true in lnd.conf (off by default). CLN: keysend plugin loaded (default), plus accept-htlc-tlv-type=34349334 and accept-htlc-tlv-type=6789998212 (v23.08+) so it keeps both Satogram TLVs. LDK: on by default. 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 the default 1 sat per recipient that’s 50 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 only sends a batch worth at least 10 sats in total (recipients * amt_per_satogram). A batch worth less is never sent as a keysend, its recipients are paid over LNURL-pay one at a time instead. Each recipient’s share of a batch is amt_per_satogram, whatever the campaign set, not 10. This means:

  • At 1 sat per recipient, a whole-sat split rounds each user’s credit down to 0 after any fee. Split and credit in msat, as the example code does.
  • If your wallet has a higher credit floor (e.g. 100 sats), hold each user’s sub-floor credits until they cross the floor.

Onboarding steps#

We maintain the opt-in list of supported wallets internally. To get added, send us:

  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 our node, or peer with us 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 we know what to expect if a campaign references a stale user.

There is no integration fee or SLA. Once the delivery fee rate is set, we add your row to the config and the next campaign starts batching to you.

Reverting opt-in#

To stop receiving batches, ask us 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 our node push you N × per_satogram sats in a single HTLC?

At the default per_satogram=1 sat, with batches of up to 50 recipients, each HTLC is up to 50 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 our node and yours has insufficient remote-side balance at HTLC time, in which case the keysend fails and every recipient in that batch is recorded as failed for that campaign. A batch that fails in flight is not retried per recipient over LNURL-pay.

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