Create Lightning Invoice

Overview

A Lightning invoice is a payment request that allows a payer to send bitcoin over the Lightning Network. You can generate a Lightning invoice by specifying the amount and optional metadata, such as a memo or expiry time. You then share the invoice with a payer, who uses it to complete the payment. For custody wallets, you can specify invoice amounts using either satoshis (valueSat) or millisatoshis (valueMsat). However, Go Lightning only accepts invoice amounts using satoshis (valueSat).

📘
Note
Currently, BitGo limits individual Lightning transactions to a value of $500 USD or less.

1. Create Lightning Invoice

Endpoint: Create a lightning invoice

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/lightning/invoice \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "valueMsat": string,   # Amount in millisatoshis
    "valueSat": string,    # Amount in satoshis
    "memo": string,        # Description of the invoice (optional)
    "expiry": number       # Expiration time in seconds (optional)
}'

  const { BitGo } = require('bitgo');
  const { getLightningWallet } = require('@bitgo/abstract-lightning');
  const accessToken = '<YOUR_ACCESS_TOKEN>';

  // Initialize the SDK
  const bitgo = new BitGo({
    accessToken: accessToken,
    env: 'test',
    customRootURI: 'https://app.bitgo-test.com',
  });

  // Enter your Lightning wallet
  const walletId = '<YOUR_WALLET_ID>'
  const existingWallet = await bitgo.coin('tlnbtc').wallets().get({ id: walletId });
  const lightningWallet = getLightningWallet(existingWallet);
    
  const invoice = await lightningWallet.createInvoice({ valueMsat: 1000n, memo: 'test', expiry: 36000 });
  console.dir(invoice);

Step Result

{
    "valueMsat": bigint,   // Amount in millisatoshis
    "valueSat": bigint,    // Amount in satoshis
    "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
}

2. (Optional) Get Lightning Invoice

You can get an individual Lightning invoice using the paymentHash or list all invoices for a wallet.

Endpoints:

Get a lightning invoice

List lightning invoices

export COIN="tlnbtc"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export PAYMENT_HASH="<YOUR_INVOICE_PAYMENT_HASH>"

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

export COIN="tlnbtc"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

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

  const { BitGo } = require('bitgo');
  const { getLightningWallet } = require('@bitgo/abstract-lightning');
  const accessToken = '<YOUR_ACCESS_TOKEN>';

  // Initialize the SDK
  const bitgo = new BitGo({
    accessToken: accessToken,
    env: 'test',
    customRootURI: 'https://app.bitgo-test.com',
  });

  // Enter your Lightning wallet
  const walletId = '<YOUR_WALLET_ID>'
  const existingWallet = await bitgo.coin('tlnbtc').wallets().get({ id: walletId });
  const lightningWallet = getLightningWallet(existingWallet);
    
  const invoice = await lightningWallet.getInvoice('yourLightningPaymentHash');
  console.dir(invoice);

  const { BitGo } = require('bitgo');
  const { getLightningWallet } = require('@bitgo/abstract-lightning');
  const accessToken = '<YOUR_ACCESS_TOKEN>';

  // Initialize the SDK
  const bitgo = new BitGo({
    accessToken: accessToken,
    env: 'test',
    customRootURI: 'https://app.bitgo-test.com',
  });

  // Enter your Lightning wallet
  const walletId = '<YOUR_WALLET_ID>'
  const existingWallet = await bitgo.coin('tlnbtc').wallets().get({ id: walletId });
  const lightningWallet = getLightningWallet(existingWallet);
    
  const invoice = await lightningWallet.listInvoices();
  console.dir(invoice);

Step Result

{
  "memo": "Payment for the coffee",
  "amtPaidMsat": "string",
  "invoice": "lnbc500n1p3zv5vkpp5x0thcaz8wep54clc2xt5895azjdzmthyskzzh9yslggy74qtvl6sdpdg3hkuct5d9hkugrxdaezqjn0dphk2fmnypkk2mtsdahkccqzpgxqyz5vqsp5v80q4vq4pwakq2l0hcqgtelgajsymv4ud4jdcrqtnzhvet55qlus9qyyssquqh2wl2m866qs5n72c5vg6wmqx9vzwhs5ypualq4mcu76h2tdkcq3jtjwtggfff7xwtdqxlnwqk8cxpzryjghrmmq3syraswp9vjr7cqry9l96",
  "paymentHash": "63d9ce82e09d16761a85116ed8b65407db4fb22f85d03573de09c480f2c6d175",
  "valueMsat": "50000",
  "expiresAt": "2022-04-01T18:46:24.677Z",
  "status": "open",
  "walletId": "59cd72485007a239fb00282ed480da1f",
  "createdAt": "2022-04-01T18:46:24.677Z",
  "updatedAt": "2022-04-01T18:46:24.677Z"
}

{
  "invoices": [
    {
      "memo": "Payment for the coffee",
      "amtPaidMsat": "string",
      "invoice": "lnbc500n1p3zv5vkpp5x0thcaz8wep54clc2xt5895azjdzmthyskzzh9yslggy74qtvl6sdpdg3hkuct5d9hkugrxdaezqjn0dphk2fmnypkk2mtsdahkccqzpgxqyz5vqsp5v80q4vq4pwakq2l0hcqgtelgajsymv4ud4jdcrqtnzhvet55qlus9qyyssquqh2wl2m866qs5n72c5vg6wmqx9vzwhs5ypualq4mcu76h2tdkcq3jtjwtggfff7xwtdqxlnwqk8cxpzryjghrmmq3syraswp9vjr7cqry9l96",
      "paymentHash": "63d9ce82e09d16761a85116ed8b65407db4fb22f85d03573de09c480f2c6d175",
      "valueMsat": "50000",
      "expiresAt": "2022-04-01T18:46:24.677Z",
      "status": "open",
      "walletId": "59cd72485007a239fb00282ed480da1f",
      "createdAt": "2022-04-01T18:46:24.677Z",
      "updatedAt": "2022-04-01T18:46:24.677Z"
    }
  ],
  "nextBatchPrevId": "string"
}

Next Steps

Pay Lightning Invoice

Overview

Note

1. Create Lightning Invoice

Step Result

2. (Optional) Get Lightning Invoice

Step Result

Next Steps

See Also