Scroll to navigation

Electrum(1) Electrum User Manual Electrum(1)

NAME

electrum - easy to use Bitcoin client

SYNOPSIS

electrum

Launch the Electrum GUI with the default options.

electrum url

Launch the Electrum GUI with a specific Bitcoin URI or a BIP70 file. See url for syntax information.

electrum [command] [options] [global_options] [positional_arguments]

Specify possible commands, options, global options, and positional arguments.

electrum help command

List detailed help for the specified command.

DESCRIPTION

Electrum is a lightweight Bitcoin wallet focused is speed, with low resource usage and simplifying Bitcoin. Startup times are instant because it operates in conjunction with high-performance servers that handle the most complicated parts of the Bitcoin system.

Electrum has a list of possible options specific to each command as well as a set of global options. Some commands also accept positional arguments at the end of the options list. Running electrum help command will list the options and positional arguments compatible with that command.

COMMANDS

Run the GUI. This is the default if no command is specified. May use the url positional argument.

Run the daemon.

Add a peer. Requires the connection_string positional argument.

Create a payment request, using the first unused address of the wallet. The address will be considered as used after this operation. If no payment is received, the address will be considered as unused if the payment request is deleted from the wallet. Requires the amount positional argument.

Add a transaction to the wallet history. Requires the tx positional argument.

Broadcast a transaction to the network. Requires the tx positional argument.

Bump the fee for an unconfirmed transaction. Requires the tx and new_fee_rate positional arguments.

Change the gap limit of the wallet. See https://support.ledger.com/hc/en-us/articles/360010892360-Address-gap-limit and https://blog.lopp.net/mind-the-bitcoin-address-gap/ for more information. Requires the new_limit positional argument.

Remove all invoices.

Clear the Lightning blacklist.

Remove all payment requests.

Close a Lightning channel. Requires the channel_point positional argument.

Close the wallet.

List the available commands.

Convert the given amount from one currency to another using the configured exchange rate source.

Convert the xtype of a master key. E.G. xpub -> ypub. Valid options are 'xprv', 'yprv', 'zprv', 'Yprv', 'Zprv', 'xpub', 'ypub', 'zpub', 'Ypub', and 'Zpub'. Requires the xkey and xtype positional arguments.

Create a new wallet. If you want to be prompted for an argument in a concealed fashion, use '?' or ':' for the argument value.

Create a MultiSig address. Requires the num and pubkeys positional arguments.

Create a new receiving address, beyond the gap limit of the wallet. See https://support.ledger.com/hc/en-us/articles/360010892360-Address-gap-limit and https://blog.lopp.net/mind-the-bitcoin-address-gap/ for more information.

Decode an invoice. Requires the invoice positional argument.

Decode a message encrypted with a public key. Requires the pubkey and encrypted positional arguments.

Delete an invoice. Requires the invoice_id positional argument.

Delete a request. Requires the request_id positional argument.

Delete a serialized transaction. Requires the tx positional argument.

This command is deprecated.

Enable Hashed TimeLock Contract settlement. See https://www.investopedia.com/terms/h/hashed-timelock-contract.asp for more information. Requires the b positional argument.

Encrypt a message with a public key. Use quotes if the message contains whitespace. Requires the pubkey and message positional arguments.

Export the channel backup. Requires the channel_point positional argument.

Freeze the funds in one of your wallet's addresses. Requires the address positional argument.

Freeze a UTXO (Unspent Transaction Output) so that the wallet will not spend it. See https://river.com/learn/bitcoins-utxo-model for more information. Requires the coin positional argument.

Return an item from the wallet storage. Requires the key positional argument.

Return the current channel's commitment transaction. Requires the channel_point positional argument.

Return the specified invoice (request for outgoing payment). Requires the invoice_id positional argument.

Return the specified payment request. Requires the request_id positional argument.

Return information regarding the transaction (for now, only the number of confirmations). The transaction must be related to the wallet. Requires the txid positional argument.

Return the local watchtower's CTN of channel. Used in regtests. Requires the channel_point positional argument.

Return the balance of a Bitcoin address. Note that this is a walletless server query, meaning that the results are not checked by SPV (Simple Payment Verification). Requires the address positional argument.

Return the transaction history of a Bitcoin address. Note that this is a walletless server query, meaning that the results are not checked by SPV (Simple Payment Verification). Requires the address positional argument.

Return the UTXO (Unspent Transaction Output) list of a Bitcoin address. Note that this is a walletless server query, meaning that the results are not checked by SPV (Simple Payment Verification). Requires the address positional argument.

Retrieve an alias. This looks in your list of contacts, and for an OpenAlias DNS record. Requires the key positional argument.

Return the balance of your wallet.

Return a configuration variable. Requires the key positional argument.

Return the current suggested fee rate (in sat/kvByte), according to the config settings or the supplied parameters.

Return the current network information.

Return the wallet's master private key.

Return the Merkle branch of a transaction included in a block. Electrum uses this to verify transactions (Simple Payment Verification). Requires the txid and height positional arguments.

Return the minimum value for gap limit that would be sufficient to discover all known addresses in the wallet.

Return the wallet's master public key.

Return the private key corresponding to a derivation path (address index). path can be either a str such as "m/0/50" or a list of ints such as [0, 50]. See https://learnmeabitcoin.com/technical/derivation-paths for more information. Requires the path positional argument.

Return the private key of an address. You may pass a single wallet address or a list of wallet addresses. Requires the address positional argument.

Return the public key of an address. Requires the address positional argument.

Return the wallet's generation seed phrase.

Return the list of known servers (connections candidates).

Return a transaction. Requires the txid positional argument.

Return the wallet's first unused address, or None if all addresses are used. An address is considered to be used if it has received a transaction or if it is used in a payment request.

Display help information. This is the same as the -h and --help options. Calling help followed by another command will display specific options for that command.

Import a channel backup. Requires the encrypted positional argument.

Import a private key. If you want to be prompted for an argument in a concealed fashion, use '?' for the argument value. Requires the privkey positional argument.

Return the wallet synchronization status.

Check if address is in the wallet. Requires the address positional argument.

Return the lightning history.

Return a list of the channels.

Return a list of invoices (requests for outgoing payments) saved in the wallet.

Return a list of lightning peers.

Return a list of incoming payment requests saved in the wallet.

Return a list of wallets open in the daemon.

Return a list of all addresses in the wallet. Use options to filter the results.

Return a list of contacts.

Return a list of unspent transaction outputs in the wallet.

Lightning Pay. Requires the invoice positional argument.

Load a wallet in the daemon.

Create a seed.

Return the lightning node ID.

Perform a normal submarine swap, which is to send on-chain BTC and receive on Lightning. Note that your funds will be locked for 24h if you do not have enough incoming capacity. Requires the onchain_amount and lightning_amount positional arguments.

Watch an address. Every time the address changes, a HTTP POST is sent to the URL. Call with an empty URL to stop watching an address. Requires the address and URL positional arguments.

Return the on-chain transaction history of the wallet.

Open a channel. Requires the connection_string and amount positional arguments.

Change the wallet password.

Create a transaction. Requires the destination and amount positional arguments.

Create a multi-output transaction. Requires the outputs positional argument.

Rebalance the channels. If trampoline is used, the channels must be with different trampolines. Requires the from_scid, dest_scid, and amount positional arguments.

Remove a local transaction, and it dependent transactions, from the wallet. Requires the txid positional argument.

Request the remove to force-close a channel. If a connection string is passed, it can be used without having a state or any backup for the channel. Assumes that the channel was originally opened with the same local peer (node_keypair). Requires the channel_point positional argument.

Reset the liquidity hints.

Restore a wallet from text, which can be a seed phrase, a master public key, a master private key, a list of Bitcoin addresses, or a list of Bitcoin private keys. If you want to be prompted for the text in a concealed fashion, use '?' or ':' for the argument value. Requires the text positional argument.

Perform a reverse submarine swap, which is to send on Lightning and receive on-chain BTC. Requires the lighting_amount and onchain_amount positional arguments.

Return contacts that match the query. Requires the query positional argument.

Create a signed raw transaction from a JSON transaction template. An example value for the jsontx argument would be: { "inputs": [ {"prevout_hash": "9d221a69ca3997cbeaf5624d723e7dc5f829b1023078c177d37bdae95f37c539", "prevout_n": 1, "value_sats": 1000000, "privkey": "p2wpkh:cVDXzzQg6RoCTfiKpe8MBvmm5d5cJc6JLuFApsFDKwWa6F5TVHpD"} ], "outputs": [ {"address": "tb1q4s8z6g5jqzllkgt8a4har94wl8tg0k9m8kv5zd", "value_sats": 990000} ] }. Requires the jsontx positional argument.

Set a configuration variable. value may be a string or a Python expression. Requires the key and value positional arguments.

Assign a label to a Bitcoin address or a transaction ID. Requires the key and label positional arguments.

Sign a message with the address key. Use quotes if the message contain whitespaces. Requires the address and message positional arguments.

Sign a transaction with the wallet keys. Requires the tx positional argument.

Sign a transaction with the provided list of private keys. Requires the tx and privkey positional argument.

Stop the daemon.

Sweep a private key, which return a transaction that spends UTXOs (Unspent Transaction Outputs) from the private key to a destination address. The transaction is not broadcast. Requires the privkey and destination positional arguments.

Unfreeze the funds in one of your wallet's addresses. Requires the address positional argument.

Unfreeze a UTXO (Unspent Transaction Output) so that the wallet will can spend it. See https://river.com/learn/bitcoins-utxo-model for more information. Requires the coin positional argument.

Check that an address is valid. Requires the address positional argument.

Verify a message signature. Requires the address, signature, and message positional arguments.

Display the version information. This is the same as the --version option.

Display information about dependencies, such as their version and path.

OPTIONS

Display help information. This is the same as using the help command with no arguments. Can be used by any command.

Display the version. This is the same as using the version command. Typically used without any command.

Specify whether to add the transaction to the wallet, so that it can be used for broadcasting afterwards. Can be used by the payto and paytomany commands.

Show the balances of the listed addresses. Can be used by the listaddresses command.

Change the address. The default is a spare address, or the source address if it is not in the wallet. Can be used by the payto and paytomany commands.

Show only change addresses. Can be used by the listaddresses command.

The Lightning network node ID or network address. Can be used by the request_force_close command.

Run the daemon in detached mode. Can be used by the daemon command.

Keep the daemon running after the GUI exits. Can be used by the gui command.

Specify whether the payment amount will be decreased (true/false). Can be used by the bumpfee command.

Specify whether the file on disk should be encrypted with the provided password. Can be used by the create, password, and restore commands.

Show only expired requests. Can be used by the list_invoices and list_requests commands.

The expiry time in seconds. Can be used by the add_request command.

Only connect to servers with a matching SSL certificate SHA256 fingerprint. To calculate this yourself: '$ openssl x509 -noout -fingerprint -sha256 -inform pem -in servercertfile.crt'. The server fingerprint should be entered as 64 hexadecimal characters. Can be used by the gui and daemon commands.

The transaction fee (absolute, in BTC). Can be used by the payto, paytomany, and sweep commands.

The source address, which must be a wallet address. Use sweep to spend from a non-wallet address. Can be used by the payto and paytomany commands.

The transaction fee rate (in sat/byte). Can be used by the payto and paytomany commands.

A float between 0.0 and 1.0, representing the fee slider position. Can be used by the getfeerate command.

The fee estimation method to use. Can be used by the getfeerate command.

Create a new address beyond the gap limit if no more addresses are available. Can be used by the add_request command.

Forget the config on exit. Can be used by the gui, add_peer, add_request, addtransaction, bumpfee, changegaplimit, clear_invoices, clear_requests, close_channel, close_wallet, create, createnewaddress, decrypt, delete_invoice, delete_request, enable_htlc_settle, export_channel_backup, freeze, freeze_utxo, get, get_channel_ctx, get_invoice, get_request, get_tx_status, get_watchtower_ctn, getalias, getbalance, getmasterprivate, getminacceptablegap, getmpk, getprivatekeyforpath, getprivatekeys, getpubkeys, getseed, gettransaction, getunusedaddress, import_channel_backup, importprivkey, is_synchronized, ismine, lightning_history, list_channels, list_invoices, list_peers, list_requests, listaddresses, listcontacts, listunspent, lnpay, load_wallet, nodeid, normal_swap, onchain_history, open_channel, password, payto, paytomany, rebalance_channels, removelocaltx, request_force_close, restore, reverse_swap, searchcontacts, setlabel, signmessage, signtransaction, unfreeze, and unfreeze_utxo commands.

The amount to convert (the default is 1). Can be used by the convert_currency command.

The currency to convert from. Can be used by the convert_currency command.

The source coins, which must be in the wallet. Use sweep to spend from a non-wallet address. Can be used by the bumpfee, payto, and paytomany commands.

Only show transactions that confirmed after the specified block height. Can be used by the onchain_history command.

Show only frozen addresses. Can be used by the listaddresses command.

Show only funded addresses. Can be used by the listaddresses command.

Specify the GUI. Valid arguments are 'qt', 'kivy', 'text', 'stdio', and 'qml'. The default is Qt. Kivy and QML are used for the Android GUI and are not included in the Debian package. The text dependencies are also not included in the Debian package. Can be used by the gui command.

Apply the command to the gossip node instead of the wallet. Can be used by the add_peer and list_peers commands.

Acknowledge that you understand the full implications of what you are about to do. Can be used by the changegaplimit and get_channel_ctx commands.

Specify the maximum number of inputs. Can be used by the sweep command.

Show the labels of the listed addresses. Can be used by the listaddresses command.

Specify the language. Can be used by the gui and make_seed commands.

Set the locktime block number. Can be used by the payto and paytomany commands.

The description of the request. Can be used by the add_request command.

The new password. Can be used by the password command.

The number of bits of entropy. Can be used by the make_seed command.

Do not verify aliases. Can be used by the payto, paytomany, and sweep commands.

Do not connect to onion servers. Can be used by the gui and daemon commands.

Do not create SegWit (Segregated Witness) wallets. See https://en.wikipedia.org/wiki/SegWit for more information. Can be used by the gui command.

-1, --oneserver
Only connect to one server. Can be used by the Can be used by the gui and daemon commands.

Specify the proxy using the [type:]host[:port] syntax (or 'none' to disable the proxy), where type is either 'socks4', 'socks5', or 'http'. Can be used by the gui and daemon commands.

Show only paid requests. Can be used by the list_invoices and list_requests commands.

The seed extension. Can be used by the create and restore commands.

Show only pending requests. Can be used by the list_invoices and list_requests commands.

The push initial amount (in BTC). Can be used by the open_channel command.

Specify whether to signal opt-in Replace-By-Fee in the transaction (true/false). Can be used by the payto and paytomany commands.

Show only receiving addresses. Can be used by the listaddresses command.

The RPC host used by the RPC daemon. See https://electrum.readthedocs.io/en/latest/jsonrpc.html for more information. Can be used by the daemon command.

The RPC port used by the RPC daemon. See https://electrum.readthedocs.io/en/latest/jsonrpc.html for more information. Can be used by the daemon command.

The RPC socket type used by the RPC daemon. Valid arguments are 'unix', 'tcp', and 'auto'. See https://electrum.readthedocs.io/en/latest/jsonrpc.html for more information. Can be used by the daemon command.

The RPC socket file location used by the RPC daemon. See https://electrum.readthedocs.io/en/latest/jsonrpc.html for more information. Can be used by the daemon command.

Specify the server using the host:port:protocol syntax, where protocol is either 't' (TCP) or 's' (SSL). Can be used by the gui and daemon commands.

Specify the seed type. Valid arguments are 'standard', 'segwit', '2fa', and '2fa_segwit'. The default is 'segwit'. Can be used by the create and make_seed commands.

Show the input and output addresses. Can be used by the onchain_history command.

Show the fiat value of transactions. Can be used by the lightning_history and onchain_history commands.

Tolerate invalid Merkle proofs from the server. See https://medium.com/crypto-0-nite/merkle-proofs-explained-6dd429623dc5 for more information. Can be used by the gui and daemon commands.

The timeout in seconds. Can be used by the add_peer and lnpay commands.

The currency to convert to. Can be used by the convert_currency command.

Only show transactions that confirmed before the specified block height. Can be used by the onchain_history command.

Do not sign the transaction. Can be used by the bumpfee, payto, and paytomany commands.

Show only unused addresses. Can be used by the listaddresses command.

Set the wallet path. Can be used by the gui, add_peer, add_request, addtransaction, bumpfee, changegaplimit, clear_invoices, clear_requests, close_channel, close_wallet, create, createnewaddress, decrypt, delete_invoice, delete_request, enable_htlc_settle, export_channel_backup, freeze, freeze_utxo, get, get_channel_ctx, get_invoice, get_request, get_tx_status, get_watchtower_ctn, getalias, getbalance, getmasterprivate, getminacceptablegap, getmpk, getprivatekeyforpath, getprivatekeys, getpubkeys, getseed, gettransaction, getunusedaddress, import_channel_backup, importprivkey, is_synchronized, ismine, lightning_history, list_channels, list_invoices, list_peers, list_requests, listaddresses, listcontacts, listunspent, lnpay, load_wallet, nodeid, normal_swap, onchain_history, open_channel, password, payto, paytomany, rebalance_channels, removelocaltx, request_force_close, restore, reverse_swap, searchcontacts, setlabel, signmessage, signtransaction, unfreeze, and unfreeze_utxo commands.

The password. Can be used by the bumpfee, create, decrypt, getmasterprivate, getprivatekeyforpath, getprivatekeys, getseed, importprivkey, load_wallet, normal_swap, open_channel, password, payto, paytomany, restore, signmessage, and signtransaction commands.

Show history for a given year. Can be used by the onchain_history command.

GLOBAL OPTIONS

Set the electrum data directory. The default is ~/.electrum.

Run electrum in offline mode.

Run electrum in portable mode, which uses ./electrum_data (electrum_data in the current directory) instead of ~/.electrum for the data directory.

Set the RPC user. See https://electrum.readthedocs.io/en/latest/jsonrpc.html for more information.

Set the RPC password. See https://electrum.readthedocs.io/en/latest/jsonrpc.html for more information.

Run in regtest (regression test) mode. The default data directory is ~/.electrum/regtest. See https://developer.bitcoin.org/examples/testing.html and https://bitcoin.stackexchange.com/questions/98462/how-to-use-electrum-with-a-local-regtest-network for more information.

Run in simnet (simulation test network) mode. The default data directory is ~/.electrum/simnet. See https://bitcoin.stackexchange.com/questions/81260/bitcoin-node-what-is-the-difference-between-simnet-and-regtest for more information.

Run in signet (signature network), which is similar to testnet but adds a signature requirement for block verification. The default data directory is ~./electrum/signet. See https://en.bitcoin.it/wiki/Signet for more information.

Run in testnet mode, which connects to Bitcoin's testnet network instead of the mainnet one. The coins on testnet have no value, which allows users to safely test functionality without risk. The default data directory is ~/.electrum/testnet. See https://developer.bitcoin.org/examples/testing.html for more information.

Set the verbosity (log level).

Set the verbosity (shortcut-filter list).

POSITIONAL ARGUMENTS

The Bitcoin address. Can be used by the freeze, getaddressbalance, getaddresshistory, getaddressunspent, getprivatekeys, getpubkeys, ismine, notify, signmessage, unfreeze, validateaddress, and verifymessage commands.

The amount to be sent (in BTC). Use '!' to send the maximum available. Can be used by the add_request, open_channel, payto, and rebalance_channels commands.

B. Can be used by the enable_htlc_settle command.

The channel point. Can be used by the close_channel, export_channel_backup, get_channel_ctx, get_watchtower_ctn, and request_force_close commands.

The coin, otherwise known as the UTXO (Unspent Transaction Output). Can be used by the freeze_utxo and unfreeze_utxo commands.

The Lightning network node ID or network address. Can be used by the add_peer and open_channel commands.

The destination Short Channel Identifier. Can be used by the rebalance_channels command.

A Bitcoin address, contact, or alias. Can be used by the payto and sweep commands.

The encrypted message. Can be used by the decrypt and import_channel_backup commands.

The from Short Channel Identifier. Can be used by the rebalance_channels command.

The block height. Can be used by the getmerkle command.

The invoice. Can be used by the decode_invoice and lnpay commands.

The invoice ID. Can be used by the delete_invoice and get_invoice commands.

The JSON transaction. An example value would be: { "inputs": [ {"prevout_hash": "9d221a69ca3997cbeaf5624d723e7dc5f829b1023078c177d37bdae95f37c539", "prevout_n": 1, "value_sats": 1000000, "privkey": "p2wpkh:cVDXzzQg6RoCTfiKpe8MBvmm5d5cJc6JLuFApsFDKwWa6F5TVHpD"} ], "outputs": [ {"address": "tb1q4s8z6g5jqzllkgt8a4har94wl8tg0k9m8kv5zd", "value_sats": 990000} ] }. Can be used by the serialize command.

The variable name. Can be used by the get, getalias, getconfig, setconfig, and setlabel commands.

The label. Can be used by the setlabel command.

The amount sent or received in a submarine swap. Set it to 'dryrun' to receive a value. Can be used by the normal_swap and reverse_swap commands.

The message. Use quotes if it contains whitespaces. Can be used by the encrypt, signmessage, and verifymessage commands.

The new fee rate. Can be used by the bumpfee command.

The new gap limit. Can be used by the changegaplimit command.

The number of signatures. Can be used by the createmultisig command.

The amount sent or received in a submarine swap. Set it to 'dryrun' to receive a value. Can be used by the normal_swap and reverse_swap commands.

A list of ["address", amount ]. Can be used by the paytomany command.

The derivation path (address index). Can be used by the getprivatekeyforpath command.

The private key. In the case of signtransaction_with_privkey a list of private keys can be used. If you want to be prompted for the privkey in a concealed fashion, use '?' for the argument value. Can be used by the getprivatekeyforpath, importprivkey, signtransaction_with_privkey, and sweep commands.

The public key. Can be used by the decrypt and encrypt commands.

The public keys. Can be used by the createmultisig command.

The query. Can be used by the searchcontacts command.

The request ID. Can be used by the delete_request and get_request commands.

The signature. Can be used by the verifymessage command.

The text, which can be a seed phrase, a master public key, a master private key, a list of Bitcoin addresses, or a list of Bitcoin private keys. If you want to be prompted for the text in a concealed fashion, use '?' or ':' for the argument value. Can be used by the restore command.

A serialized transaction in hexadecimal. Can be used by the addtransaction, broadcast, bumpfee, deserialize, signtransaction, and signtransaction_with_privkey commands.

The transaction ID. Can be used by the get_tx_status, getmerkle, gettransaction, and removelocaltx commands.

The value, which may be a string or a Python expression. Can be used by the setconfig command.

A Bitcoin URI or a BIP70 file. The Bitcoin URI syntax is bitcoin:address[?amount=amount][?label=label][?message=message]. Can be used by the gui command.

A standard web URL that can receive HTTP POST commands. Can be used by the notify command.

The XKey. Can be used by the convert_xkey command.

The XType. Can be used by the convert_xkey command.

AUTHOR

Documentation author: Soren Stoutner <soren@debian.org>

7 June 2024 version 4.5.5