This tool is for interacting with v1 BitGo bitcoin wallets. New v2 Bitcoin wallets or wallets for other coins should use our new cli tool instead.
This package provides a NodeJS program (bitgo), which is a (mostly) complete command-line interface to BitGo wallets. It also contains some useful client-side-only commands for key generation.
NodeJS must be installed as a prerequisite.
$ npm install -g bitgo-cli
Running bitgo -h will produce usage information.
$ bitgo -h
usage: bitgo [-h] [-v] [-e] [-j]
BitGo Command-Line
Optional arguments:
-h, --help Show this help message and exit.
-v, --version Show program's version number and exit.
-e ENV, --env ENV BitGo environment to use: prod (default) or test. Can
also be set with the BITGO_ENV environment variable.
-j, --json output JSON (if available)
subcommands:
{login,logout,token,status,wallets,wallet,balance,labels,setlabel,removelabel,addresses,newaddress,tx,unlock,lock,sharewallet,shares,acceptshare,cancelshare,freezewallet,removewallet,unspents,unspent,consolidate,fanout,sendtoaddress,newkey,splitkeys,verifysplitkeys,recoverkeys,dumpwalletuserkey,newwallet,shell,help,createtx,signtx,sendtx,listWebhooks,addWebhook,removeWebhook,util}
login Sign in to BitGo
logout Sign out of BitGo
token Get or set the current auth token
status Show current status
wallets Get list of available wallets
wallet Set or get the current wallet
balance Get current wallet balance
labels Show labels
setlabel Set a label on any address (in curr. wallet context)
removelabel Remove a label on an address (in curr. wallet context)
addresses List addresses for the current wallet
newaddress Create a new receive address for the current wallet
tx List transactions on the current wallet
unlock Unlock the session to allow transacting
lock Re-lock the session
sharewallet Share the current wallet with another user
shares List outstanding wallet shares (incoming and outgoing)
acceptshare Accept a wallet share invite
cancelshare Cancel or decline a wallet share invite
freezewallet Freeze (time-lock) the current wallet
removewallet Remove a wallet from your account
unspents Show unspents in the wallet
unspent Same as above command
consolidate Consolidate unspents in a wallet
fanout Fan out unspents in a wallet
sendtoaddress Create and send a transaction
newkey Create a new BIP32 keychain (client-side only)
splitkeys Create set of BIP32 keys, split into encrypted shares.
verifysplitkeys Verify the public keys contained in the output file
from the splitkeys command
recoverkeys Recover key(s) from an output file of 'splitkeys'
dumpwalletuserkey Dumps a user xprv given a wallet and passphrase
newwallet Create a new Multi-Sig HD wallet
shell Run the BitGo command shell
help Display help
createtx Create an unsigned transaction (online) for signing
(the signing can be done offline)
signtx Sign a transaction (can be used offline) with an
input transaction JSON file
sendtx Send a transaction for co-signing to BitGo
listWebhooks Show webhooks for the current wallet
addWebhook Add a webhook for the current wallet
removeWebhook Remove a webhook for the current wallet
util Utility commands
By default, bitgo will use the production Bitcoin network, and will authenticate with www.bitgo.com. In order to use BitGo's test environment at test.bitgo.com, either use -e test on the command line, or set the following environment variable:
$ export BITGO_ENV=test
The testnet environment is a completely separate namespace from the BitGo production database. You will need to set up separate accounts on test.bitgo.com for testing purposes. Note that in the test environment, while standard Authy codes still work for 2FA, it is also possible to use a code of 0000000 (7 zeroes).
The tool maintains one current login session per environment (prod or test). The sessions are persisted in JSON format files in ~/.bitgo. Each session maintains the user's current auth token, and maintains a current wallet. All of the commands that operate on a wallet use this current wallet context. In order to operate on a different wallet, it must first be selected using the wallet command.
A number of the commands support outputting in JSON format as well as the normal human-readable format. To enable JSON output, use the -j command line flag before the command, for example:
$ bitgo -j status
{
"env": "test",
"network": "testnet",
"sessionFile": "/Users/me/.bitgo/test.json",
"user": "me@me.com",
"wallet": "2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao"
}
Many of the commands have interactive flows, prompting for needed information as they go. Generally, these interactive prompts can be bypassed by providing the corresponding information through a command-line flag.
Authenticate with BitGo, establishing a session.
$ bitgo login
Email: user@domain.com
Password: ********
2-Step Verification Code: 0000000
*** Logged in as user@domain.com
...
Logout of the current session. Sessions expire in 60 minutes by default.
$ bitgo logout
Show the current auth token:
$ bitgo token
bab7b73dec9501b8b210ec8d68e1ac26a88b7b8c3c4f6811935d793d627c7d54
Set the current auth token; this is an alternate way of changing sessions, or can be used to install a long-lived API token provided by BitGo:
$ bitgo token 24b7b73dec9501b8b210ec8d68e1ac26a88b7b8c3c4f6811935d793d627c7d54
*** Logged in as user@domain.com
Show the current session status.
$ bitgo status
Network: prod
Session file: ~/.bitgo/prod.json
Current User: user@domain.com
Logged in
Current wallet: 3N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
List the wallets available to the user, with balances. Indicates which wallet is currently selected.
$ bitgo wallets
Get or set the current wallet.
$ bitgo wallet # shows current wallet information
$ bitgo wallet 3 # selects wallet 3 in the wallets list
$ bitgo wallet <addr> # selects wallet by address
$ bitgo wallet <name> # selects wallet by name
Get the balance of the current wallet.
$ bitgo balance # get balance in BTC
$ bitgo balance -c # get confirmed balance in BTC
$ bitgo balance -u bits # get balance in bits
$ bitgo balance -u sat # get balance in satoshis
Show address labels associated with the current wallet, or all wallets.
$ bitgo labels # shows address labels on current wallet
$ bitgo labels -a # shows address labels on all wallets
Label a Bitcoin address in the context of the current wallet.
$ bitgo setlabel <address> "My label here"
Remove label from a Bitcoin address in the context of the current wallet.
$ bitgo removelabel <address>
Show receive addresses for the current wallet, and optionally change addresses. Shows
$ bitgo addresses # show receive addresses only
$ bitgo addresses -c # include change addresses
$ bitgo -j addresses # show addresses in JSON format
Generate a new receive address for the current wallet
$ bitgo newaddress # get a new receive address
$ bitgo newaddress -c # get a new change <address>
$ bitgo newaddress -l "foo" # get a new receive address labeled "foo"
List transactions on the current wallet.
$ bitgo tx # show last 25 transactions
$ bitgo tx -n 100 # show last 100 transactions
$ bitgo -j tx # show last 25 transactions in JSON format
In order to transact, a BitGo session must first be unlocked, by providing an additional 2-step verification (Authy) code. The send command handles prompting for this automatically, but the wallet can also be unlocked explicitly.
$ bitgo unlock 1234567 # unlock the session with current Authy code
*** Unlocked session
Explicitly lock the session, preventing further transactions from taking place.
$ bitgo lock
*** Locked session
Share the current wallet with a user by giving them share, spend, or admin priviliges on the wallet. If no wallet is specified, it will use the current wallet. You must have admin status on the wallet to use this command.
$ bitgo sharewallet 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Share Wallet 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao:
Email address of recipient: user@domain.com
Role ( [a]dmin | [s]pender | [v]iewer ): s
Optional comment for recipient: Spend limit is 100 BTC
Wallet password: *******
2-step Verification Code: 0000000
*** Wallet share created (id=55cd2f4cf1f414280c2c926af4c47874)
Lists outstanding wallet shares (incoming and outgoing)
$ bitgo shares
Outgoing Shares:
ID Role To Wallet Message
55cd2f4cf1f414280c2c926af4c47874 spender user@domain.com 0 Spend limit is 100 BTC
Accept a wallet share invite
$ bitgo acceptshare 47874c4fa629c2c082414f1fc4f2dc55
BitGo Password: ********
wallet share accepted
Cancel or decline a wallet share invite
$ bitgo cancelshare 47874c4fa629c2c082414f1fc4f2dc55
*** Wallet share canceled
Freeze a BitGo wallet. This command effectively time-locks a wallet, so that BitGo will refuse to sign any transactions until the freeze expires. Be careful when freezing a wallet, as there is no way to unfreeze a wallet without either waiting for the time to expire without help from BitGo support.
$ bitgo freezewallet -d 60
Please confirm you wish to freeze wallet 'My Wallet' for 60 seconds.
BitGo will not sign any transactions on this wallet until the freeze expires.
Type 'go' to confirm: go
Wallet frozen until 2015-02-03T22:46:56.352Z
Remove a wallet from your BitGo account. If the wallet is shared, and you are not the last admin, it removes your access to the wallet but does not affect other users' access. If you are the last admin on the wallet, it will mark the wallet as deleted and it will not currently be recoverable without assistance from BitGo.
$ bitgo removewallet 2MzoQpTopwMD7dfufGeHHvZYfEDrMdxibTM
Type 'yes' to confirm removing wallet 2MzoQpTopwMD7dfufGeHHvZYfEDrMdxibTM: yes
*** Removed wallet 2MzoQpTopwMD7dfufGeHHvZYfEDrMdxibTM
Show a list of unspents on the current wallet, optionally filtering by minimum confirms.
$ bitgo unspents # show all unspents
$ bitgo unspents -c 6 # show unspents with at least 6 confirms
Same command as above
Consolidate the unspents on the current wallet into fewer, bigger unspents, optionally setting the target count of unspents.
$ bitgo consolidate # consolidate all unspents into one
$ bitgo consolidate -t 5 # consolidate all unspents until there are only five unspents left
$ bitgo consolidate -i 10 # consolidate all unspents into one, but only use up to 10 inputs per consolidation transaction
Fan out the unspents on the current wallet into a set of more, equally large, unspents.
$ bitgo fanout -t 20 # fan out all the unspents into a total of 20 unspents
Send a transaction. This command provides a guided flow, but the needed info may also be provided on the command line.
$ bitgo -e test send
Current wallet: 2N9VaC4SDRNNnEy6G8zLF8gnHgkY6LV9PsX
Send Transaction:
Destination address: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Amount (in BTC): 0.5
Wallet passcode: ********************
Optional comment: paying Mike for lunch
Please confirm sending BTC 0.5000 + 0.0001 blockchain fee to 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Type 'go' to confirm: go
2-step Verification Code: 0000000
*** Unlocked session
*** Sent transaction 9ef2042647ceb0b1ec8f18733ab46d11c330b4449549fe37a9c559e170806d0e
Create a new BIP32 root key. This is a client-side only operation. It does not require the user to be authenticated with BitGo, and does not contact the BitGo server. Additional entropy may be provided on the command line.
$ bitgo -j newkey
{
"seed": "72cc2a8728529c17432031ca5a37851b9dfe254f5427f7ebedb6c15abac22575",
"xpub": "xpub661MyMwAqRbcGi5Yk7XnMMp9tkfe4hVGpo6QEgmkzjxCEzjxzJJU458dJWJjdErQbVJg5fb6iGvb2o4GKEYbycXMWo1CXYiw4RhexSYZsh2",
"xprv": "xprv9s21ZrQH143K4E15e5zmzDsRLiq9fEmRTaAoSJN9SQRDNCQpSkzDWGp9TDErubsFHbUwHVEwWgpMssULihY2Rayek52VTVdj1wUXeiV2c56"
}
This is a client-side utility command which assists in generating a batch of BIP32 keys which are split using Shamir Secret Sharing, and have the shares encrypted with separate passwords (each known by a separate person, generally). It provides a guided flow, as well as command-line args.
$ splitkeys -h
usage: bitgo splitkeys [-h] [-m M] [-n N] [-N NKEYS] [-p PREFIX] [-e ENTROPY]
Optional arguments:
-h, --help Show this help message and exit.
-m M number of shares required to reconstruct a key
-n N total number of shares per key
-N NKEYS, --nkeys NKEYS
total number of keys to generate
-p PREFIX, --prefix PREFIX
output file prefix
-e ENTROPY, --entropy ENTROPY
additional user-supplied entropy
Verifies the xpubs generated by the splitkeys command. This command is useful for verifying that the shares contained in the input JSON file correspond to the xpub(s) listed in the JSON file
$ bitgo verifysplitkeys
Verify Split Keys
Input file (JSON): keys.json
Comma-separated list of key indices to recover: 0,1
Processing 2 keys: 0,1
Password 0: *********
Password 1: ***********
Decrypting Key #0, Part #0
Decrypting Key #0, Part #1
Decrypting Key #1, Part #0
Decrypting Key #1, Part #1
[
{
"index": 0,
"xpub": "xpub661MyMwAqRbcF2CSKyTp1Xv9gSBvkdVQsPh5NwSRaErAXVWhtfYBZeuZxVJA8fayUJoPa4rtMZAWUzVG5XESKvCqTvvED5gErrZuxsyDPrP"
},
{
"index": 1,
"xpub": "xpub661MyMwAqRbcGrqGfmNuJK41iS4kETkofD6mnNT1CMGcuoeJCvWjNtwzgqfSqXsUYUC7NJWTgnrtxHmy93xGTDe7ZbfXbtgxa9LpD7yD5NQ"
}
]
A client-side utility for recovering keys generated by splitkeys.
$ bitgo recoverkeys -h
usage: bitgo recoverkeys [-h] [-f FILE] [-k KEYS]
Optional arguments:
-h, --help Show this help message and exit.
-f FILE, --file FILE the input file (JSON format)
-k KEYS, --keys KEYS comma-separated list of key indices to recover
Print a wallet's xprv, which is decrypted using the passphrase. If the wallet's encrypted keychain is not stored by BitGo, there will be no xprv to print.
$ bitgo dumpwalletuserkey
Wallet password: ********
Type 'go' to confirm that you want to dump the wallet private key to output: go
xprv9s21ZrQH143K4CD2eRTRFO5Uq8dtjTm9mmNvADopmCRNcRjnELpSZ1C3GZJLNa9YbuLaUPWQMM6fQD5jrKxZ3mFsomcvbsyw9Poq8WVcqXw
Create a new BitGo HD 2-of-3 Multi-sig wallet. This is a guided flow with instructions. You will need to provide 1 xprv and 1 xpub, or 2 xpubs in order to create the wallet.
Please be aware that creating a wallet in this manner does not produce a recovery KeyCard. You are fully responsible for backing up your keys. If you lose access to your keys and passcode, BitGo cannot help you recover your funds.
$ bitgo newwallet
Current User: ben+0@bitgo.com
Create New Wallet undefined
First, we need the user keychain. Enter a BIP32 xprv below, or press
return to generate one automatically. Your user key is encrypted locally
with your password, and stored on BitGo's server.
User key (xprv or xpub): xprv9s21ZrQH143K4VhG7qJD...
Next, we need the backup keychain. Enter a BIP32 xpub below. It is recommended
to generate the backup keychain on a different machine using reliable
BIP32 key generation software. For instance, you can use the 'keychain'
sub-command to generate a keychain
Backup key (xpub): xpub661MyMwAqRbcG7xHfBQqNLMNS...
Name this wallet: My Command Line Wallet
Enter BitGo password: ********************
*** Created wallet 2N3So1bs9fuLeA3MrsBGPmkaYMXGWQn1HWG
Launch the BitGo shell, which simply allows you to run commands without prefixing them with bitgo. No other shell functionality is provided. Use Ctrl-C or Ctrl-D to exit.
bitgo shell
[bitgo @ My Cool Wallet]Ƀ status
Prints all of the commands and subcommands that bitgo-cli responds to, along with short explanations of each command
Creates an unsigned transaction and saves it to a JSON file. This file can then be brought to an offline machine for signing using signtx.
$ bitgo createtx -h
usage: bitgo createtx [-h] [-d DEST] [-a AMOUNT] [-f FEE] [-c COMMENT]
[-p PREFIX]
Optional arguments:
-h, --help Show this help message and exit.
-d DEST, --dest DEST the destination address
-a AMOUNT, --amount AMOUNT
the amount in BTC
-f FEE, --fee FEE fee to pay for transaction
-c COMMENT, --comment COMMENT
optional private comment
-p PREFIX, --prefix PREFIX
output file prefix
$ bitgo createtx
Current wallet: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Create Unsigned Transaction
Destination address: 2MzoQpTopwMD7dfufGeHHvZYfEDrMdxibTM
Amount (in BTC): 0.3
Blockchain fee (blank to use default fee calculation): 0.001
Optional private comment: payroll funds
Created unsigned transaction for 0.3000 BTC + 0.001 BTC blockchain fee to 2MzoQpTopwMD7dfufGeHHvZYfEDrMdxibTM
Wrote tx20154211455.json
Signs an unsigned transcation (using JSON file from createtx). Can be performed offline.
$ bitgo signtx -h
usage: bitgo signtx [-h] [-f FILE] [--confirm] [-k KEY] [-p [PREFIX]]
Optional arguments:
-h, --help Show this help message and exit.
-f FILE, --file FILE the input transaction file (JSON format)
--confirm skip interactive confirm step -- be careful!
-k KEY, --key KEY xprv (private key) for signing
-p [PREFIX], --prefix [PREFIX]
optional output file prefix
$ bitgo signtx
Input transaction file: tx20154211455.json
Private BIP32 key (xprv): xprv9w5AP8PS54E8vWpadxu24uAdArdQbdvkAKvkYGfo1Y187QGVTgWktL6PGothdFAowKxtZwdQEmEcHdfEzwYtqSdRCzFVM2XvDUtxB4CGS4F
You are signing a transaction from the wallet: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Comment: payroll funds
Output #1: 0.3 BTC to 2MzoQpTopwMD7dfufGeHHvZYfEDrMdxibTM
Output #2: 0.199 BTC to 2PMxwFLAtvXnKC6tv4gpzDs9iWqNArjfMM (verified change address back to wallet)
Type 'go' to confirm: go
Signed transaction using the key provided.
Wrote tx20154211455.signed.json
Sends a half-signed transaction on a wallet to BitGo for co-signing and propogation to the Bitcoin network. Takes input from a filename (JSON constructed by signtx) or a pure transaction hex.
$ bitgo sendtx -h
usage: bitgo sendtx [-h] [-t TXHEX] [-f [FILE]]
Optional arguments:
-h, --help Show this help message and exit.
-t TXHEX, --txhex TXHEX
the transaction hex to send
-f [FILE], --file [FILE]
optional input file containing the tx hex
$ bitgo sendtx
Current wallet: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Send Transaction
Transaction (hex or file): tx20154211455.signed.json
2-step Verification Code: 6753460
*** Unlocked session
*** Sent transaction 0c41cef5a1b89c3f9387440169b38fb2465b30e0d23c92368f82c8f571182e03
Lists the webhooks for the current wallet
$ bitgo listWebhooks
Current wallet: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Webhooks:
Type NumConfirmations URL
transaction 3 http://www.yoursite.com/partner/webhooks
Adds a webhook to the current wallet.
$ bitgo -u http://www.yoursite.com/partner/webhooks -n 3 -t transaction
Current wallet: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
Webhooks:
Type NumConfirmations URL
transaction 3 http://www.yoursite.com/partner/webhooks
Removes a webhook from the current wallet.
$ bitgo removeWebhook -u http://www.yoursite.com/partner/webhooks -t transaction
Current wallet: 2N6d5SYvu1xQeSQnpZ4VNVZ6TcRYcqkocao
{ removed: 1 }
Miscellaneous utility commands
$ bitgo util -h
usage: bitgo util [-h] {recoverlitecoin} ...
Optional arguments:
-h, --help Show this help message and exit.
Utility commands:
{recoverlitecoin,recoverbch,recoversafehdbch}
recoverlitecoin Helper tool to craft transaction to recover Litecoin
mistakenly sent to BitGo Bitcoin multisig addresses
on the Litecoin network
recoverbch Helper tool to craft transaction to recover BCH
mistakenly sent to BitGo Bitcoin multisig addresses
on the BTC network
recoversafehdbch Helper tool to craft transaction to recover BCH from
migrated legacy SafeHD wallets
BitGo CLI contains a number of utility functions for recovering funds from inaccessible wallets. The following recoveries can be performed:
- Recover BCH and BTG from a migrated legacy SafeHD Wallet
- Recover LTC sent to a BTC wallet
- Recover BCH sent to a BTC wallet (non-SegWit address)
- Recover BTC sent to a BCH wallet
Run bitgo util -h for a full list of recovery functions and their respective commands.
All recoveries can be accessed via bitgo util and require the following pieces of information:
- The destination address to send the recovered funds to
- The wallet passphrase of the legacy SafeHD wallet
You will be prompted to enter this data after starting the tool. This tool will construct, sign, and broadcast the transaction, so once the tool is complete, any transactions are irreversible.
All recoveries can be accessed via bitgo util and require the following pieces of information:
- The wallet ID of the wallet that received the 'wrong funds'
- The transaction ID of the misdirected transaction
- A destination address to send the recovered funds to (should belong to the original chain funds were sent from)
- The wallet passphrase (or xprv) for the wallet that received the misplaced funds
You will be prompted to enter this data after starting the tool.
Example:
$ bitgo login (enter login information)
$ bitgo util recoverbch --test
This tool will help you construct a transaction to recover BCH mistakenly sent to a non-SegWit BTC address.
================================================================================
Please enter the wallet ID of the BTC wallet that received the funds: 5a21bbe965662fd407b07e3f794d4a8b
Please enter the transaction ID of your faulty transaction: 842a9193cca39e4e4f5e7db43a402ccf93661b35f8a9df26f40aeddf27644c36
Please enter the address you wish to recover your BCH to: 2NEv4PivtrqShHdnA6y6eC2QkeHh4YijZED
================================================================================
Grabbing info for faulty tx...
Getting unspents on output addresses...
Building inputs for recovery transaction...
Found 0.213123 BCH at address 2Mxq8pmNCx25UEWJDBxZ8nPj8katuH7hq84
Found lost 0.213123 BCH.
Building outputs for recovery transaction. Funds will be sent to 2NEv4PivtrqShHdnA6y6eC2QkeHh4YijZED...
Built inputs and outputs. Signing the transaction...
================================================================================
Found an encrypted user keychain. Please enter your wallet passphrase: ***************
================================================================================
This is your half-signed recovery transaction. Please verify this transaction independently.
Once you half verified your transaction, you may submit it to BitGo support for co-signing and broadcast.
Half-signed transaction:
{
"txHex": "0200000001364c6427dfed0af426dfa9f8351b6693cf2c403ab47d5e4f4e9ea3cc93912a8401000000b600473044022076ce7e9ddccbb5ccc826e4c396cb01a0ce2a33dd55a6843c654b2405f403747202203f7041e2231769545d4db7f7d7c873b6dd4ae9fbe9343b00be59cf8efd0bb3ff4100004c69522102d0d6955ed934bda10e4c6b19c215c77428ffd11d95815c6871dfcc8270a2d48c21030957e339f7e0e9f734e0cd4966dd6d8c415eb5301fb193b8b48df7bf7a3c5c8821039d16e1cd3f57f4786c410f7e42d429501d1e9fc3a4904ae6682c2e6633a447e553aeffffffff01b01845010000000017a914edb2da8ef295baa4155b42acb8a4eac11d9a0e088700000000"
}
================================================================================
Saved recovery transaction info to ./bchr-842a919.signed.json
After running the tool, bitgo-cli will save a local recovery JSON file. You should verify the transaction using a public transaction decoder - if you are satisfied, submit the recovery transaction file to support@bitgo.com for co-signing.
For developers on bitgo-cli, the following must be run before writing new code.
$ npm install