Developer Guide
Migration Guide
Migrating to Credit Backed Payments
27 min
drop your lnd node entirely send and receive payments through the voltage payments api backed by a line of credit prerequisites you've read docid 7szaymjg8lkjcmiwjkub (auth changes, concept mapping, status mapping, amount handling) your business is eligible for a voltage line of credit (us based, approved states) migration steps apply for a line of credit post collateral create payments environment and wallet set up webhooks migrate sending migrate receiving implement reconciliation loop parallel run cut over and decommission node step 1 apply for a line of credit follow the docid\ kd563u5vevsbcaymvcan guide to submit your application you'll need organization structure and tin beneficial owner information (25%+ ownership) officer/director details estimated monthly send and receive volumes after submitting, voltage reviews your application if approved, you'll receive an email with your approved credit amount, billing cycle, and collateral requirements step 2 post collateral if collateral is required navigate to your billing dashboard in the voltage ui send btc to the provided multi sig address (secured by distributed keys) once the required amount confirms, your account is enabled for mainnet payments step 3 create payments environment and wallet go to the payments product in the voltage dashboard create a new environment create a new wallet — do not check "i want to use a team infrastructure node" choose your wallet currency btc — payments denominated in bitcoin, no quotes needed usd — payments denominated in us dollars, requires the quotes api for every payment generate an api key for the environment after this step you'll have organization id , environment id , wallet id your x api key (if usd) your line of credit id for the quotes api usd wallets require a quote before every send and receive see docid 1qzxwddcqh5wuzv6qf 0a and docid\ jymho26n377vgern3on i for the full workflow step 4 set up webhooks this step is identical to the node backed path register a webhook to receive real time payment events curl "https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/webhooks" \\ \ request post \\ \ header "content type application/json" \\ \ header "x api key your api key" \\ \ data '{ "id" "b0fc9829 f139 4035 bb14 4a4b6cd58f0e", "organization id" "{organization id}", "environment id" "{environment id}", "url" "https //your domain com/webhook", "name" "migration webhook", "events" \[ { "send" "succeeded" }, { "send" "failed" }, { "receive" "generated" }, { "receive" "completed" }, { "receive" "expired" }, { "receive" "failed" } ] }' save the shared secret from the response implement signature verification using the x voltage signature and x voltage timestamp headers see the docid\ pdeh 4et9aqawca5q91na guide for full details step 5 migrate sending the payments api send endpoint is the same regardless of whether your wallet is node backed or credit backed lightning payment (btc wallet) before (lnd rest) curl cacert tls cert \\ \ header "grpc metadata macaroon $(xxd ps u c 1000 admin macaroon)" \\ https //your node voltage cloud 8080/v2/router/send \\ \ request post \\ \ data '{ "payment request" "lntbs1500n1p ", "timeout seconds" 60, "fee limit msat" 1000, "no inflight updates" true }' after (payments api) curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "68d00852 8dd8 4c71 94d2 91c84695da78", "wallet id" "{wallet id}", "currency" "btc", "type" "bolt11", "data" { "payment request" "lntbs1500n1p ", "amount" { "currency" "btc", "amount" 150000, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000, "unit" "msats" } } }' usd wallets you must first obtain a quote via post /quotes , then include the quote id and set currency "usd" in the payment request see docid 1qzxwddcqh5wuzv6qf 0a for the full two step flow on chain payment before (lnd rest) curl cacert tls cert \\ \ header "grpc metadata macaroon $(xxd ps u c 1000 admin macaroon)" \\ https //your node voltage cloud 8080/v1/transactions \\ \ request post \\ \ data '{ "addr" "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49", "amount" 15000, "sat per vbyte" 10 }' after (payments api) curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "2ec1e783 19b4 4c10 8181 66336a6232bd", "wallet id" "{wallet id}", "currency" "btc", "type" "onchain", "data" { "address" "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49", "amount" { "currency" "btc", "amount" 15000000, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000000, "unit" "msats" }, "description" "test payment" } }' step 6 migrate receiving lightning invoice (btc wallet) before (lnd rest) curl cacert tls cert \\ \ header "grpc metadata macaroon $(xxd ps u c 1000 admin macaroon)" \\ https //your node voltage cloud 8080/v1/invoices \\ \ request post \\ \ data '{ "value msat" 150000, "memo" "test payment", "expiry" 3600 }' after (payments api) — step 1 create the receive payment curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "11ca843c bdaa 44b6 965a 39ac550fcef7", "wallet id" "{wallet id}", "currency" "btc", "payment kind" "bolt11", "amount" { "amount" 150000, "currency" "btc", "unit" "msats" }, "description" "test payment", "expiration" 3600 }' after — step 2 fetch the invoice curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/11ca843c bdaa 44b6 965a 39ac550fcef7' \\ \ header 'x api key your api key' the data payment request field contains the bolt11 invoice string usd wallets obtain a quote first, then include quote id and set currency "usd" with the amount in cents see docid\ jymho26n377vgern3on i for the full workflow on chain receive before (lnd rest) curl cacert tls cert \\ \ header "grpc metadata macaroon $(xxd ps u c 1000 admin macaroon)" \\ https //your node voltage cloud 8080/v1/newaddress?type=taproot pubkey after (payments api) curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "11ca843c bdaa 44b6 965a 39ac550fcef8", "wallet id" "{wallet id}", "currency" "btc", "payment kind" "onchain", "amount" { "amount" 150000000, "currency" "btc", "unit" "msats" }, "description" "on chain deposit" }' fetch the payment to get data address step 7 implement reconciliation loop same as the node backed path set up a cron job (every 1–5 minutes) that lists recently updated payments and upserts them into your database see the docid\ pdeh 4et9aqawca5q91na guide under "reconciliation loop" for the full implementation step 8 parallel run run both integrations side by side since you're migrating off the node entirely, focus your verification on the payments api path verification checklist send a lightning payment via the payments api → completed receive a lightning payment via the payments api → invoice generated, completed send an on chain payment via the payments api → completed receive an on chain payment via the payments api → address generated, completed webhooks fire for all events reconciliation loop catches all payments step 9 cut over and decommission node once your parallel run is verified, decommission your lnd node follow these steps in order 1\ stop all direct lnd api calls disable your old integration all payment traffic should now flow through the payments api 2\ download seed phrase and scb backup as a precaution before closing channels seed phrase node dashboard → backup & export → seed phrase backup → reveal seed phrase static channel backup node dashboard → backup & export → download channel backup store both securely offline 3\ close all channels use thunderhub or lncli to close every open channel cooperative close is preferred — it confirms faster (next block vs timelock period) and costs less in fees via lncli lncli closechannel funding txid=\<funding txid> output index=\<output index> via thunderhub navigate to channels → close each channel individually force closing channels locks your funds for a timelock period (typically 144 blocks / 1 day) only force close if a peer is unresponsive 4\ wait for closures to confirm on chain monitor your pending channel closures in thunderhub or via lncli pendingchannels all closures must confirm before proceeding 5\ withdraw remaining on chain balance send all remaining on chain funds to your treasury wallet lncli sendcoins addr=\<your treasury address> sweepall or use thunderhub's send interface 6\ verify zero balances confirm both on chain and channel balances are zero lncli walletbalance lncli channelbalance both should return zero 7\ delete node from voltage infrastructure dashboard navigate to your node in the infrastructure product and delete it 8\ cancel infrastructure plan if no longer needed if you have no other nodes, cancel your infrastructure plan from the voltage billing settings what you no longer manage responsibility before (direct lnd) after (credit backed) node uptime you monitor and restart not applicable channels you open, close, rebalance not applicable liquidity you manage capacity + treasury not applicable routing lnd pathfinding or custom not applicable tls certificates load, rotate, distribute not applicable macaroons bake, secure, inject not applicable backups (seed + scb) you maintain secure copies not applicable node unlocking unlock after every restart not applicable billing with a line of credit, you're billed on a regular cycle based on your approved terms your billing dashboard shows current credit utilization billing cycle dates payment history for details, see docid edzyjyqded0mqf4oy9 c