Bitcoin Lightning Network

Overview

The Bitcoin Lightning Network utilizes off-chain payment channels to enable fast transactions at little to no cost. Transactions settle instantly between participants without waiting for on-chain block confirmations. The Lightning Network also supports microtransactions, making small payments more feasible. Final balances record on-chain whenever a channel closes.

At a high level, the Lightning Network functions by:

Funding transaction: Two parties lock a certain amount of bitcoin into a multi-signature address on the Bitcoin blockchain, serving as collateral for the Lightning channel.
Balance setup: Both parties contribute an agreed amount to the locked bitcoin. The split doesn't have to be even.
Off-chain transactions: Once a channel is open, parties can exchange off-chain payments back and forth instantly and with minimal fees.
Commitment transactions: With every transaction, both parties sign an updated commitment transaction reflecting the new balance.
Closing the channel: Either party can close the channel at any time by broadcasting the latest signed transaction to the blockchain, settling the final balances on-chain.

Fortunately, if you create a Lightning wallet with BitGo, you don't have to manage liquidity or channels. BitGo handles these complexities for you, ensuring seamless transactions with reliable liquidity. BitGo also handles the infrastructure and key management. The only aspect that you have to manage are the payments.

Operations like creating invoices and making payments use Lightning-specific endpoints. Other basic operations, such as listing transfers and creating addresses, leverage the same asset-agnostic endpoints you use elsewhere on the BitGo platform.

Wallets Types

Currently, the only Lightning wallet type that BitGo offers is custody wallet. Unlike other wallet types at BitGo, this is single-signature custody hot wallet. However, you still have security of qualified custody, insured up to $250,000,000.

Ticker Symbols

Mainnet	Testnet
lnbtc	tlntbc

Units

On the Bitcoin network, bitcoin is divisible by 10^-8 and the base unit is a satoshi (sat). However, on the Lightning Network, bitcoin is divisible by 10^-12 and the base unit is a millisatoshi (msat):

1 bitcoin = 100,000,000 satoshi or 100,000,000,000 millisatoshi
1 satoshi = 0.00000001 bitcoin or 1,000 millisatoshis
1 millisatoshi = 0.00000000001 bitcoin or 0.001 satoshi

Tokens

The Lightning blockchain doesn't natively support tokens.

Fees

Lightning transactions have no minimum or default fees.

Create Wallet

When you create a Lightning wallet, BitGo creates a Lightning node with a whitelisted Lightning Service Provider (LSP). This process takes approximately 20 minutes to complete. BitGo sends you an email notification when the wallet is ready to use.

Endpoint: Generate Wallet

cURL
JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export COIN="tbtc4"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export LABEL="<YOUR_WALLET_NAME>"
export PASSPHRASE="<YOUR_BITGO_LOGIN_PASSPHRASE>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST:3080/api/v2/$COIN/wallet/generate \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "label": "'"$LABEL"'",
    "passphrase": "'"$PASSPHRASE"'",
    "enterprise": "'"$ENTERPRISE_ID"'"
    "type": "hot",
    "subType": "lightningCustody" # required for lightning wallets
}'

Create Address

Creating an address is an important step to opening a channel on the Lightning Network, because it prompts the Lightning node to generate a single-signature address for the funding transaction.

Endpoint: Create Address

cURL
JavaScript

1
2
3
4
5
6
7
8
export COIN="tlnbtc"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/address \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Create Invoice

Payments on the Lightning Network occur through invoices between channel partners. Create a Lightning invoice for another party to pay.

Endpoint: Create a lightning invoice

cURL
JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
export COIN="tbtc4"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ADDRESS="<DESTINATION_ADDRESS>"
export AMOUNT="<AMOUNT_IN_BASE_UNITS>"
export WALLET_PASSPHRASE="<YOUR_WALLET_PASSPHRASE>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/lightning/invoice \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "valueMsat": string,   # Amount in millisatoshis (required)
    "memo": string,        # Description of the invoice (optional)
    "expiry": number       # Expiration time in seconds (optional)
}'

Step Result

JSON

1
2
3
4
5
6
7
8
9
{
    "value": number,       // Amount in millisatoshis
    "memo": string,        // Description of the invoice
    "paymentHash": string, // Unique identifier of the payment
    "invoice": string,     // Encoded payment request
    "walletId": string,    // ID of the BitGo wallet that created the invoice
    "status": open,        // Current status of the invoice (e.g., "open")
    "expiresAt": string    // ISO timestamp when the invoice expires
}

Pay Invoice

Pay a Lightning invoice created by another party.

Endpoint: Lightning - Pay a Lightning Invoice

cURL
JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export COIN="tbtc4"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ADDRESS="<DESTINATION_ADDRESS>"
export AMOUNT="<AMOUNT_IN_BASE_UNITS>"
export WALLET_PASSPHRASE="<YOUR_WALLET_PASSPHRASE>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST:3080/api/v2/$COIN/wallet/$WALLET_ID/lightning/payment \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "invoice": string,                       # Encoded payment request (required)
    "passphrase": "'"$WALLET_PASSPHRASE"'",  # Wallet passphrase (required)
    "amountMsat": string,     # Amount to pay in millisatoshis (optional, required for zero-amount invoices)
    "feeLimitMsat": string,   # Maximum fee to pay in millisatoshis
    "feeLimitRatio": number,  # Maximum fee expressed as a ratio of the payment amount
    "sequenceId": string,     # Custom identifier for tracking the payment
    "comment": string         # Additional note or comment for internal reference
}'

Step Result

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "txRequestId": string,        // Unique identifier for the transaction request
    "txRequestState": delivered,  // State of the transaction request
    "paymentStatus": {
      "status": pending,          // Payment status
      "paymentHash": string,      // Unique identifier of the payment
      "paymentPreimage": string,  // Payment preimage (proof of payment)
      "amountMsat": string,       // Final amount paid in millisatoshis
      "feeMsat": string,          // Network fees paid in millisatoshis
      "failureReason": string     // Reason for failure if payment failed
    },
    "transfer": {
      "id": string,
      "coin": string,
      "wallet": string,
      "walletType": string,
      "enterprise": string,
      "organization": string,
      "txid": string,
      "state": string, // initialized, unconfirmed, confirmed
      "type": string, // send, receive
      "value": number
      "valueString": string,
      "coinSpecific": {
        "isOffchain": boolean,
        "invoice": string
      },
    }
}

Is this page helpful?