Lightning Network solves Bitcoin's fundamental problem: on-chain transactions are expensive (up to $100 per transfer) and slow (10–60 minutes). Imagine a micropayment service — each $0.01 payment requires a fee 1000 times larger. With Lightning Network Daemon from Lightning Labs, fees drop to 1–10 satoshis ($0.0001–0.001), and confirmation takes seconds. But integrating Bitcoin Lightning via LND is non-trivial: you need to set up a gRPC client with macaroon authentication, manage channel liquidity, and implement payment processing without losses. Our team has over 5 years of experience: we have connected LND to payment gateways, exchanges, and DeFi applications. At peak times, on-chain fees can exceed $100 per transfer — Lightning reduces them to fractions of a cent, achieving up to 99.98% cost savings. According to Lightning Labs, implementing LND can save up to 99% on transaction costs. For a business processing 10,000 transactions per month, switching from on-chain ($50 per tx) to Lightning ($0.01 per tx) results in monthly savings of $499,990. Let's dive into the technical details.
What is LND and How It Works
LND is a software node for the Lightning Network. It requires:
- A synchronized Bitcoin node (Bitcoind or neutrino light mode)
- Open payment channels with peers in the network
- Liquidity management: funds on your side of the channel for outgoing payments, and on the opposite side for incoming
Payment channels are 2-of-2 multisig contracts on Bitcoin L1. LND manages channel state off-chain, publishing only channel opening and closing to the blockchain. Invoice-based payments: the recipient creates an invoice (BOLT-11 payment request), and the payer pays it. The invoice contains a payment hash — the HTLC mechanism guarantees atomicity.
What APIs Does LND Provide for Integration?
LND offers two APIs: gRPC (primary, full-featured) and REST (wrapper). For production — gRPC, which performs 10 times better than REST for high-throughput scenarios. Compare:
| Feature | gRPC | REST |
|---|---|---|
| Performance | High (HTTP/2, binary protocol) | Medium (JSON, HTTP/1.1) |
| Functionality | Full set of RPC methods (including streaming) | Partial coverage |
| Authentication | TLS + macaroon | TLS + macaroon (Hex/Base64) |
| Recommendation | Primary choice | For simple integrations |
Authentication via TLS certificate + macaroon (capability-based token):
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import fs from 'fs';
const TLS_CERT = fs.readFileSync('/home/bitcoin/.lnd/tls.cert');
const MACAROON = fs.readFileSync('/home/bitcoin/.lnd/data/chain/bitcoin/mainnet/admin.macaroon');
const sslCreds = grpc.credentials.createSsl(TLS_CERT);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator((_, callback) => {
const metadata = new grpc.Metadata();
metadata.add('macaroon', MACAROON.toString('hex'));
callback(null, metadata);
});
const credentials = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
const packageDef = protoLoader.loadSync('rpc.proto', { keepCase: true });
const lnrpc = grpc.loadPackageDefinition(packageDef) as any;
const lightning = new lnrpc.lnrpc.Lightning('localhost:10009', credentials);
Macaroon is not just a token — it's capability-based authorization. You can create invoice.macaroon (invoice creation only), readonly.macaroon (read-only), or custom ones with IP and time restrictions. Never expose admin.macaroon to applications — only minimal required permissions.
Core Operations
Creating an Invoice (Receiving Payment)
function addInvoice(amountSats: number, memo: string): Promise<Invoice> {
return new Promise((resolve, reject) => {
lightning.AddInvoice({
value: amountSats,
memo,
expiry: 3600,
}, (err: any, response: any) => {
if (err) reject(err);
else resolve({
paymentRequest: response.payment_request,
rHash: response.r_hash.toString('hex'),
addIndex: response.add_index.toString(),
});
});
});
}
The BOLT-11 string starts with lnbc (mainnet) or lntb (testnet). This is what the user scans with their wallet.
Tracking Incoming Payments
Two approaches:
Polling — LookupInvoice by r_hash. Simple but not optimal.
Streaming subscriptions — SubscribeInvoices streams all updates in real-time:
function subscribeInvoices(onSettled: (invoice: SettledInvoice) => void) {
const stream = lightning.SubscribeInvoices({
settle_index: 0,
});
stream.on('data', (invoice: any) => {
if (invoice.state === 1) {
onSettled({
rHash: invoice.r_hash.toString('hex'),
amountPaidSats: Number(invoice.amt_paid_sat),
settledAt: Number(invoice.settle_date),
memo: invoice.memo,
});
}
});
stream.on('error', (err: Error) => {
setTimeout(() => subscribeInvoices(onSettled), 5000);
});
}
Important: settle_index must be persisted. On application restart, subscribe from the last processed settle_index, otherwise you'll miss payments received during downtime.
Outgoing Payments
async function sendPayment(paymentRequest: string): Promise<string> {
return new Promise((resolve, reject) => {
const routerStub = new lnrpc.routerrpc.Router('localhost:10009', credentials);
const stream = routerStub.SendPaymentV2({
payment_request: paymentRequest,
timeout_seconds: 60,
fee_limit_sat: 100,
max_parts: 4,
});
stream.on('data', (payment: any) => {
if (payment.status === 2) {
resolve(payment.payment_preimage.toString('hex'));
} else if (payment.status === 3) {
reject(new Error(`Payment failed: ${payment.failure_reason}`));
}
});
});
}
SendPaymentV2 (router RPC) is preferable over the old SendPayment — it supports MPP (Multi-Path Payments) and better handles routing errors.
Step-by-Step LND Integration Plan
-
Node Setup and Authentication. Deploy an LND node (mainnet/testnet) or connect to an existing one. Create a TLS certificate and macaroon with minimal permissions (e.g., invoice.macaroon for receiving payments). Ensure the node is synced and channels are open.
-
Implement gRPC Client. Use protobuf definitions from the LND repository. Configure combined credentials (TLS + macaroon). Add reconnect logic with exponential backoff.
-
Payment Handling. Implement invoice creation (AddInvoice) and subscription to settle events (SubscribeInvoices) with persistent settle_index. For outgoing payments, use SendPaymentV2 with MPP support.
-
Liquidity Management and Monitoring. Set up automatic channel rebalancing via charge-lnd or bos. Connect monitoring (Prometheus + Grafana) to track balances and uptime.
Get a consultation for your project — we'll help assess the scope of work.
Why Liquidity Management is Critical
This is an ongoing operational task. The main issues:
- Inbound liquidity: To receive payments, you need liquidity on the peer's side of the channel. A new node often cannot receive payments. Solutions: Lightning Service Providers (Bitrefill Thor, Loop In, Amboss Magma) — paid inbound liquidity rental; open a channel the other way.
- Channel rebalancing: Over time, channels become unbalanced — all funds on one side. LND loop out — submarine swap for rebalancing: moves Lightning funds on-chain, redistributes. Used automatically by tools like charge-lnd or bos (Balance of Satoshis).
- Fee policy: For routing others' payments through your node, you charge base_fee + fee_rate. Proper fee settings affect routing efficiency.
How to Track Payments in LND
We've already covered two methods: polling and streaming. For production, use streaming with persistent settle_index. This guarantees no payment is lost. On downtime, the application resumes subscription from the last index.
LNURL and Wallet Integration
LNURL is a protocol extension on top of LN. Key types:
| LNURL Type | Description | Example Use Case |
|---|---|---|
| LNURL-pay | User scans QR, wallet automatically requests an invoice of the required amount | Donations, store payments |
| LNURL-withdraw | Allows user to receive funds via LN | Payouts, cashback |
| Lightning Address | Human-readable address like [email protected] | Simplifies sending payments |
Example backend for LNURL-pay:
app.get('/.well-known/lnurlp/:username', async (req, res) => {
res.json({
callback: `https://yourdomain.com/lnurlp/${req.params.username}/pay`,
maxSendable: 100_000_000,
minSendable: 1_000,
metadata: JSON.stringify([['text/plain', `Pay ${req.params.username}`]]),
tag: 'payRequest',
});
});
app.get('/lnurlp/:username/pay', async (req, res) => {
const { amount } = req.query;
const invoice = await createInvoice(Number(amount) / 1000);
res.json({ pr: invoice.paymentRequest, routes: [] });
});
What's Included in Integration
Standard LND integration includes:
- Setting up or connecting to an existing LND node
- gRPC client with TLS + macaroon authentication
- Invoice creation and subscription to incoming payments with persistent settle_index
- Outgoing payment processing with MPP support
- LNURL-pay endpoint (if needed)
- Basic error handling and reconnect logic
The operational part (channel management, liquidity) is a separate concern, depending on payment flow scale. We support projects, ensuring infrastructure stability.
LND Integration Checklist
- Deploy LND node (mainnet/testnet) or connect to existing
- Configure TLS certificate and macaroon with minimal permissions
- Implement gRPC client with reconnect handling
- Create invoices and subscribe to settle events with persistent index
- Implement outgoing payments with MPP and error handling
- Add LNURL-pay endpoint (if required)
- Test on testnet with load simulation (e.g., 1000 invoices per minute)
- Deploy to production with monitoring of uptime and channel balances
Assess your project — contact us for a consultation. Basic integration timeline: 1–2 weeks. Get a quote for your tasks.
Example savings: replacing on-chain payment with Lightning reduces fee from $50 to less than $0.01, a 99.98% reduction. At 10,000 transactions per month, savings amount to $499,990. This is not theory — we have implemented such solutions for clients. Contact us to discuss your LND integration.