ImportAccount

ImportAccount imports an account backed by an account extended public key. The master key fingerprint denotes the fingerprint of the root key corresponding to the account public key (also known as the key with derivation path m/). This may be required by some hardware wallets for proper identification and signing.

The address type can usually be inferred from the key's version, but may be required for certain keys to map them into the proper scope.

For BIP-0044 keys, an address type must be specified as we intend to not support importing BIP-0044 keys into the wallet using the legacy pay-to-pubkey-hash (P2PKH) scheme. A nested witness address type will force the standard BIP-0049 derivation scheme, while a witness address type will force the standard BIP-0084 derivation scheme.

For BIP-0049 keys, an address type must also be specified to make a distinction between the standard BIP-0049 address schema (nested witness pubkeys everywhere) and our own BIP-0049Plus address schema (nested pubkeys externally, witness pubkeys internally).

NOTE: Events (deposits/spends) for keys derived from an account will only be detected by lnd if they happen after the import. Rescans to detect past events will be supported later on.

Source: walletrpc/walletkit.proto

gRPC

rpc ImportAccount (ImportAccountRequest) returns (ImportAccountResponse);

REST

HTTP Method	Path
POST	/v2/wallet/accounts/import

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'walletrpc/walletkit.proto'], loaderOptions);
const walletrpc = grpc.loadPackageDefinition(packageDefinition).walletrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new walletrpc.WalletKit(GRPC_HOST, creds);
let request = {
  name: <string>,
  extended_public_key: <string>,
  master_key_fingerprint: <bytes>,
  address_type: <AddressType>,
  dry_run: <bool>,
};
client.importAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "account": <Account>,
//    "dry_run_external_addrs": <string>,
//    "dry_run_internal_addrs": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletrpc/walletkit.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletkit_pb2 as walletrpc, walletkit_pb2_grpc as walletkitstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = walletkitstub.WalletKitStub(channel)
request = walletrpc.ImportAccountRequest(
  name=<string>,
  extended_public_key=<string>,
  master_key_fingerprint=<bytes>,
  address_type=<AddressType>,
  dry_run=<bool>,
)
response = stub.ImportAccount(request)
print(response)
# {
#    "account": <Account>,
#    "dry_run_external_addrs": <string>,
#    "dry_run_internal_addrs": <string>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  name: <string>, // <string> 
  extended_public_key: <string>, // <string> 
  master_key_fingerprint: <string>, // <bytes> (base64 encoded)
  address_type: <string>, // <AddressType> 
  dry_run: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v2/wallet/accounts/import`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "account": <object>, // <Account> 
//    "dry_run_external_addrs": <array>, // <string> 
//    "dry_run_internal_addrs": <array>, // <string> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v2/wallet/accounts/import'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'name': <string>,
  'extended_public_key': <string>,
  'master_key_fingerprint': base64.b64encode(<bytes>),
  'address_type': <AddressType>,
  'dry_run': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "account": <Account>,
#    "dry_run_external_addrs": <string>,
#    "dry_run_internal_addrs": <string>,
# }

Shell

$ lncli wallet accounts import --help

NAME:
   lncli wallet accounts import - Import an on-chain account into the wallet through its extended public key.

USAGE:
   lncli wallet accounts import [command options] extended_public_key name

DESCRIPTION:
   
  Imports an account backed by an account extended public key. The master
  key fingerprint denotes the fingerprint of the root key corresponding to
  the account public key (also known as the key with derivation path m/).
  This may be required by some hardware wallets for proper identification
  and signing.

  The address type can usually be inferred from the key's version, but may
  be required for certain keys to map them into the proper scope.

  If an account with the same name already exists (even with a different
  key scope), an error will be returned.

  For BIP-0044 keys, an address type must be specified as we intend to not
  support importing BIP-0044 keys into the wallet using the legacy
  pay-to-pubkey-hash (P2PKH) scheme. A nested witness address type will
  force the standard BIP-0049 derivation scheme, while a witness address
  type will force the standard BIP-0084 derivation scheme.

  For BIP-0049 keys, an address type must also be specified to make a
  distinction between the standard BIP-0049 address schema (nested witness
  pubkeys everywhere) and our own BIP-0049Plus address schema (nested
  pubkeys externally, witness pubkeys internally).

  NOTE: Events (deposits/spends) for keys derived from an account will
  only be detected by lnd if they happen after the import. Rescans to
  detect past events will be supported later on.
  

OPTIONS:
   --address_type value            (optional) specify the type of addresses the imported account should generate
   --master_key_fingerprint value  (optional) the fingerprint of the root key (derivation path m/) corresponding to the account public key
   --dry_run                       (optional) perform a dry run
   

Messages

walletrpc.ImportAccountRequest

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type	REST Placement
name A name to identify the account with.	string	string	body
extended_public_key A public key that corresponds to a wallet account represented as an extended key. It must conform to a derivation path of the form m/purpose'/coin_type'/account'.	string	string	body
master_key_fingerprint The fingerprint of the root key (also known as the key with derivation path m/) from which the account public key was derived from. This may be required by some hardware wallets for proper identification and signing. The bytes must be in big-endian order.	bytes	string	body
address_type An address type is only required when the extended account public key has a legacy version (xpub, tpub, etc.), such that the wallet cannot detect what address scheme it belongs to.	AddressType	string	body
dry_run Whether a dry run should be attempted when importing the account. This serves as a way to confirm whether the account is being imported correctly by returning the first N addresses for the external and internal branches of the account. If these addresses match as expected, then it should be safe to import the account as is.	bool	boolean	body

walletrpc.ImportAccountResponse

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type
account The details of the imported account.	Account	object
dry_run_external_addrs The first N addresses that belong to the external branch of the account. The external branch is typically used for external non-change addresses. These are only returned if a dry run was specified within the request.	string[]	array
dry_run_internal_addrs The first N addresses that belong to the internal branch of the account. The internal branch is typically used for change addresses. These are only returned if a dry run was specified within the request.	string[]	array

Nested Messages

walletrpc.Account

Field	gRPC Type	REST Type
name The name used to identify the account.	string	string
address_type The type of addresses the account supports.	AddressType	string
extended_public_key The public key backing the account that all keys are derived from represented as an extended key. This will always be empty for the default imported account in which single public keys are imported into.	string	string
master_key_fingerprint The fingerprint of the root key from which the account public key was derived from. This will always be zero for the default imported account in which single public keys are imported into. The bytes are in big-endian order.	bytes	string
derivation_path The derivation path corresponding to the account public key. This will always be empty for the default imported account in which single public keys are imported into.	string	string
external_key_count The number of keys derived from the external branch of the account public key. This will always be zero for the default imported account in which single public keys are imported into.	uint32	integer
internal_key_count The number of keys derived from the internal branch of the account public key. This will always be zero for the default imported account in which single public keys are imported into.	uint32	integer
watch_only Whether the wallet stores private keys for the account.	bool	boolean

Enums

walletrpc.AddressType

Name	Number
UNKNOWN	0
WITNESS_PUBKEY_HASH	1
NESTED_WITNESS_PUBKEY_HASH	2
HYBRID_NESTED_WITNESS_PUBKEY_HASH	3
TAPROOT_PUBKEY	4