Set Up Lightning Custody Wallets

Create a custody Lightning wallet on BitGo. See the Guide.

You create a custody Lightning wallet by calling the Generate Wallet endpoint with subType: "lightningCustody". BitGo creates a Lightning node with a hosting service provider and initializes it. This process can take up to 24 hours. BitGo sends you an email notification when the wallet is ready.

Prerequisites: Sign a custody Lightning license (custodyLightningWallet for custody wallets, custodyGoLightning for Go Lightning) for your enterprise by contacting support@bitgo.com.

API Reference

// 1. Create Lightning Wallet
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export COIN="tlnbtc"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export LABEL="<YOUR_WALLET_NAME>"
export WALLET_PASSPHRASE="<YOUR_BITGO_LOGIN_PASSPHRASE>"
export PASSCODE_ENCRYPTION_CODE="<YOUR_BITGO_PASSPHRASE_ENCRYPTION_CODE>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"

curl -X POST \
http://$BITGO_EXPRESS_HOST/api/v2/$COIN/wallet/generate \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
    "label": "'"$LABEL"'",
    "passphrase": "'"$WALLET_PASSPHRASE"'",
    "passcodeEncryptionCode": "'"$PASSCODE_ENCRYPTION_CODE"'",
    "enterprise": "'"$ENTERPRISE_ID"'",
    "type": "hot",
    "subType": "lightningCustody"
}'

// 1. Create Lightning Wallet
const { BitGo } = require('bitgo');

// Fill in with actual access token
const accessToken = '<YOUR_ACCESS_TOKEN>';

// Initialize the SDK
const bitgo = new BitGo({
    accessToken: accessToken,
    env: 'test',
});

// Generate hot wallet
async function createCustodialHotWallet() {
    const newWallet = await bitgo.coin('tlnbtc').wallets().generateWallet({
    label: '<YOUR_WALLET_NAME>',
    passphrase: '<YOUR_BITGO_LOGIN_PASSPHRASE>',
    passcodeEncryptionCode: '<YOUR_BITGO_PASSPHRASE_ENCRYPTION_CODE>',
    enterprise: '<YOUR_ENTERPRISE_ID>',
    subType: 'lightningCustody'
});

    console.log(JSON.stringify(newWallet, undefined, 2));
}

Response

// 1. Create Lightning Wallet Response
{
  "wallet": {
    "id": "72b85f1a4c3e9d07e6a1b2c3d4e5f6a7",
    "users": [
      {
        "user": "72b72a3bdd5701812b3f784eb2fa0c2f",
        "permissions": [
          "admin",
          "spend",
          "view"
        ]
      }
    ],
    "coin": "tlnbtc",
    "label": "Test Custody Lightning Wallet",
    "m": 1,
    "n": 1,
    "keys": [
      "72b85f0ab3f2826ef7473890d18aa9c4"
    ],
    "keySignatures": {},
    "enterprise": "72b72a3edd5701812b3f789375106c94",
    "organization": "72b72a3edd5701812b3f78a2b28e59df",
    "bitgoOrg": "BitGo Trust",
    "tags": [
      "72b85f1a4c3e9d07e6a1b2c3d4e5f6a7",
      "72b72a3edd5701812b3f789375106c94"
    ],
    "disableTransactionNotifications": false,
    "freeze": {},
    "deleted": false,
    "approvalsRequired": 1,
    "isCold": false,
    "coinSpecific": {
      "keys": [
        "72b85f0a614462ddfc812f4fd0a63f77",
        "72b85f0a4791c666c83dc149693120ba"
      ]
    },
    "admin": {
      "policy": {
        "date": "2025-03-26T17:48:18.000Z",
        "id": "72b85f1a4c3e9d07e6a1b2c4a97e6af4",
        "label": "default",
        "rules": [],
        "version": 0,
        "latest": true
      }
    },
    "clientFlags": [],
    "walletFlags": [],
    "allowBackupKeySigning": false,
    "recoverable": true,
    "startDate": "2025-03-26T17:48:18.000Z",
    "type": "hot",
    "buildDefaults": {},
    "customChangeKeySignatures": {},
    "hasLargeNumberOfAddresses": false,
    "hasReceiveTransferPolicy": false,
    "creator": "72b72a3bdd5701812b3f784eb2fa0c2f",
    "walletFullyCreated": true,
    "subType": "lightningCustody",
    "config": {},
    "offchain": {
      "inboundBalance": "0",
      "inboundPendingBalance": "0",
      "inboundUnsettledBalance": "0",
      "outboundBalance": "0",
      "outboundPendingBalance": "0",
      "outboundUnsettledBalance": "0",
      "outboundLockedBalance": "0",
      "outboundReservedBalance": "0",
      "outboundSpendableBalance": "0"
    },
    "balanceString": "0",
    "confirmedBalanceString": "0",
    "spendableBalanceString": "0",
    "pendingApprovals": []
  },
  "userKeychain": {
    "id": "72b85f0ab3f2826ef7473890d18aa9c4",
    "pub": "xpub661MyMwAqRbcFKQKbgT6uA46wmi5FrqrYoJjUzQjnPU5VY6Pk7nyqn2Jg9oHdn4gd1Eh8idDbh6wQ4mWMZ8CXBGBLGvoBbva3MpkDVmbjxL",
    "ethAddress": "0x01e0c185c0652fc9d6b67fcb36149aa67a17fab4",
    "source": "user",
    "type": "independent",
    "encryptedPrv": "{\"v\":2,\"m\":65536,\"t\":3,\"p\":4,\"salt\":\"QctWCJgRfjBprOokWtVSyA==\",\"iv\":\"LtLFwupLBu/rCRPa\",\"ct\":\"c8GMgHn4l2Gcf611NtShgZoKYTO...\"}"
  },
  "userAuthKeychain": {
    "id": "72b85f0a614462ddfc812f4fd0a63f77",
    "pub": "xpub661MyMwAqRbcH4SU8XsxRzbNkZWr3zB1Qksxp9b7mqv8f2btQgofwBQixHZFUrUSrtS8r8yH7cs6pMwYQUWuAg13upsCb72v7cnfY5sU7Xx",
    "ethAddress": "0x83c3e1f73925c9013b1ae05da76eb67dbd85e374",
    "source": "user",
    "type": "independent",
    "coinSpecific": {
      "tlnbtc": {
        "purpose": "userAuth"
      }
    },
    "encryptedPrv": "{\"v\":2,\"m\":65536,\"t\":3,\"p\":4,\"salt\":\"/7zejGExkzNQ+g0jzFPhvw==\",\"iv\":\"pF+g1ZGHHaTKJZ6J\",\"ct\":\"Wn7w0/Xn9yVAnbxNk50r8E36...\"}"
  },
  "nodeAuthKeychain": {
    "id": "72b85f0a4791c666c83dc149693120ba",
    "pub": "xpub661MyMwAqRbcGERpcMr6F9LLKAfH6yAgqFQG3Nm6CAYVvFmYo6NLWunC6zpvrYn9kNpnEmhNCaqeqU4X1oNMgYh976Qnj1ydLfzdDeQQwtw",
    "ethAddress": "0xd5c67379ca532f60a1a4aae6e4aca3498cf40a85",
    "source": "user",
    "type": "independent",
    "coinSpecific": {
      "tlnbtc": {
        "purpose": "nodeAuth"
      }
    },
    "encryptedPrv": "{\"v\":2,\"m\":65536,\"t\":3,\"p\":4,\"salt\":\"uRoFMvgfvp4+rb0/DfQ3Zw==\",\"iv\":\"gxVYKeW687fjTESE\",\"ct\":\"aPnCKPQbMovmK4kpkJc4Rzy...\"}"
  },
  "responseType": "LightningWalletWithKeychains",
  "encryptedWalletPassphrase": "{\"v\":2,\"m\":65536,\"t\":3,\"p\":4,\"salt\":\"2SSebtpNWcuo8nGaJgqpIA==\",\"iv\":\"zBM7EXO2AeeQAVBw\",\"ct\":\"BPEhERjs086iTbatr0W2ycs...\"}"
}