Summary
Allow the buyer to optionally request their payout in on-chain Bitcoin instead of Lightning, by issuing a /onchain command before the seller releases funds. The bot would perform a submarine swap (Lightning → on-chain) and charge an additional fee to cover swap costs.
Proposed UX Flow
- A buy or sell order reaches the
WAITING_BUYER_INVOICE state (bot is waiting for the buyer to supply a Lightning invoice).
- Instead of sending a Lightning invoice, the buyer sends
/onchain <bitcoin_address>.
- The bot validates the address (mainnet bech32 / p2pkh / p2sh).
- The bot replies with a fee breakdown and asks for confirmation:
⛓️ On-chain settlement requested
Amount: 100,000 sats
Swap fee: 1,500 sats (1.5%)
Network fee: 500 sats (estimated)
────────────────────────────
You will receive: ~98,000 sats
Address: bc1q...xyz
Confirm? [Yes] [No]
- On confirmation, the order is flagged with
onchain_payout: true and the address is stored.
- The rest of the flow is unchanged: seller pays the hold invoice → both parties confirm fiat → seller releases.
- At release, instead of paying a Lightning invoice, the bot performs a submarine swap (e.g. via Loop Out, Boltz, or a configured swap provider) and sends on-chain.
- The swap fee is recorded on the order and shown in the final receipt.
Data Model Changes
New fields added to the Order schema:
onchain_payout — boolean, flags the order for on-chain settlement
onchain_address — the destination Bitcoin address provided by the buyer
onchain_tx_id — the txid after the swap is broadcast
onchain_fee_sats — the actual swap fee charged, in satoshis
Fee Structure
Two new configurable environment variables:
| Variable |
Description |
Default |
ONCHAIN_SWAP_FEE_PERCENT |
Percentage of the order amount charged for the swap |
0.015 (1.5%) |
ONCHAIN_MIN_AMOUNT_SATS |
Minimum order size to allow on-chain settlement |
10000 |
The existing MAX_FEE and community FEE_PERCENT are applied first. The swap fee is additive and shown separately in the breakdown.
New Command
/onchain <bitcoin_address>
- Only available to the buyer of the order
- Only valid while the order is in
WAITING_BUYER_INVOICE status
- Replaces the need to provide a Lightning invoice for that order
- Disabled if the order amount is below
ONCHAIN_MIN_AMOUNT_SATS
Summary
Allow the buyer to optionally request their payout in on-chain Bitcoin instead of Lightning, by issuing a
/onchaincommand before the seller releases funds. The bot would perform a submarine swap (Lightning → on-chain) and charge an additional fee to cover swap costs.Proposed UX Flow
WAITING_BUYER_INVOICEstate (bot is waiting for the buyer to supply a Lightning invoice)./onchain <bitcoin_address>.onchain_payout: trueand the address is stored.Data Model Changes
New fields added to the Order schema:
onchain_payout— boolean, flags the order for on-chain settlementonchain_address— the destination Bitcoin address provided by the buyeronchain_tx_id— the txid after the swap is broadcastonchain_fee_sats— the actual swap fee charged, in satoshisFee Structure
Two new configurable environment variables:
ONCHAIN_SWAP_FEE_PERCENT0.015(1.5%)ONCHAIN_MIN_AMOUNT_SATS10000The existing
MAX_FEEand communityFEE_PERCENTare applied first. The swap fee is additive and shown separately in the breakdown.New Command
/onchain <bitcoin_address>WAITING_BUYER_INVOICEstatusONCHAIN_MIN_AMOUNT_SATS