Method & parameters	Response	Notes
Generate a wallet on your BitBox
"seed" : { "source" : "source", "U2F_counter" : "counter", "entropy" : "entropy", "key" : "key", "filename" : "filename" }	"seed" : "success"	Source: `create`, `backup`, `U2F_create`, or `U2F_load`. `create` securely creates a new wallet on the device. `U2F_create` securely creates a new U2F master key on the device. In both cases, a backup `filename` is automatically saved to the micro SD card that contains the wallet seed, the U2F master key, and the device name. `backup` creates a wallet from a backup `filename` on the micro SD card. `U2F_load` sets the U2F master key as that contained in the backup. `key` is the passphrase used when cryptographically generating a wallet. The `key` is recommended to be strengthened (e.g. PBKDF2) by the client software in order to make brute force attacks on the backup more difficult. `entropy` is optional if using the `create` mode. User-supplied `entropy` can be added to the output of the device's hardware random number generator when creating a wallet. `counter` sets the U2F counter value. It is a 32-bit number (without quotes) and is optional if using the `U2F_create` or `U2F_load` modes. If not specified, the U2F counter value stored inside the device is unchanged. To avoid setting the counter too low, the client code is recommended to set the counter to be the `unix_time_seconds * ave_u2f_calls_per_second`. A safe choice is 1 call every 10 seconds, giving over 1000 years until the counter is filled.
Backup the existing wallet to a micro SD card
"backup" : { "source" : "U2F/HWW/all", "key" : "key", "filename" : "filename" }	"backup" : "success"	Saves a backup of the wallet to a file `filename` in a `digitalbitbox` folder on the micro SD card. `source` specifies the secret to back up (hardware wallet seed, U2F master key, or both); it is optional for backward compatibility and defaults to `all`. `key` is the wallet passphrase and used to verify the integrity of the hardware wallet seed in the backup file; it is ignored is source is `U2F`. The SD card should be formatted (FAT file system) before use.
"backup" : "list"	"backup" : "files"	Lists the files and folders in the `digitalbitbox/` folder on the micro SD card.
"backup" : { "source" : "U2F/HWW", "check" : "filename", "key" : "key" }	"backup" : "success"	Check if the backup `filename` on the micro SD card matches the corresponding secret stored in the BitBox (either main or hidden wallet). `source` is either the hardware wallet seed (HWW), or the U2F master key; it is optional for backward compatibility and defaults to `HWW`. `key` is the (stretched) password for the seeded wallet; it is ignored when checking the U2F master key.
"backup" : "erase"	"backup" : "success"	Erase everything in the `digitalbitbox/` folder on the micro SD card.
"backup" : { "erase" : "filename" }	"backup" : "success"	Erase `filename` in the `digitalbitbox/` folder on the micro SD card.
Set a password
"password" : "password"	"password" : "success"	A `password` is required that has a length of at least 4 characters. The password needs to be sent only once and is used to encrypt all communication via the AES-256-CBC algorithm. Special symbols (UTF-8) are allowed.
Access a hidden wallet
"hidden password" : { "password" : "hidden_password", "stretched_password" : "hidden_password" }	"hidden password" : "success"	As a plausible deniability security feature, once set, a `hidden password` can be used to access a hidden wallet. For firmware versions 2.3.0 or higher, if a different hidden password is set, a different hidden wallet is created. Resetting the hidden password for a previous hidden wallet will load the previous hidden wallet (specific to a given wallet seed). Using a hidden password to recover from a backup file will cause the hidden wallet to be loaded as the standard wallet, adding more plausibility. The hidden wallet is erased if the device is factory reset, a new wallet is created onboard, or a wallet is recovered from a backup.
Sign using a private key
"sign" : { "meta" : "metadata", "data" : "hasharray", "checkpub" : "pubkeyarray" }	"echo" : { "meta" : "metadata", "data" : "hasharray", "checkpub" : "pubkeyarray", "pin" : "lock_pin" }	The `sign` command produces ECDSA signatures of hashes given in `data`. Two `sign` commands must be sent in a row. The first command produces an encrypted verfication message. The second command (see below) returns an array of `signatures` and corresponding signing `pubkeys`. Verification messages allow two-factor authentication (2FA) for highest security. Data: `hasharray` contains a list of hashes and the keypaths used to sign each hash: `[{'hash':'hash 1', 'keypath':'keypath 1'}, ... ]`. Multiple hashes can be signed in one command. Each hash must be 64-characters long (representing a 32-byte hexadecimal value). Checkpub: `pubkeyarray` contains a list of compressed pubkeys and associated keypaths. This is used for checking if a pubkey, e.g. for a change output, is part of the wallet: `[{'pubkey':'pubkey 1', 'keypath':'keypath 1'}, ... ]`. Any number of pubkeys can be checked. The result is added to the encrypted verification message: `[{'pubkey':'pubkey 1', 'present':true}, ... ]`. Meta: `metadata` is included 'as is' in the returned encrypted verfication message. This is typically a hash of the unsigned transaction. The JSON value of the `echo` response is encrypted with the verification key (see `verifypass` below). For locked devices, the `lock_pin` is the single-use PIN required to 'unlock', or allow, signatures to be created and returned after sending the second `sign` command.
"sign" : { "pin" : "lock_pin" }	"sign" : { "recid" : "recid", "sig" : "signature" }	The second `sign` command turns on the LED for touch button user confirmation. Its reply contains the signatures. For an unlocked device, `pin` is ignored, and an empty command can be sent instead: `{'sign': ''}`. Returned signatures are not post-processed. DER encoding for a standard transaction is to be done in the client software. `recid` is the recoverable ID that can be used to derive the public key from the signature. ECDSA signing without pre- or post-processing provides compatibility 'out-of-the-box' with multisignature protocols, altcoins, or other custom implementations.
Set a verification key for two-factor authentication (2FA)
"verifypass" : "operation"	"verifypass" : "reply"	Operation: `export`, `create`, or `{'ecdh': 'pubkey A'}`. `create` uses the hardware random number generator to create a random 64 character hexadecimal string as a verification key. `{'ecdh': 'pubkey'}` implements Diffie-Hellman key exchange using the secp2561 elliptic curve. `export` saves the key to the micro SD card in a plaintext file named `verification.txt`. The reply is `success` for `create` or `export`. For `ecdh`, the reply is `{'ecdh': 'pubkey B'}`. To avoid MITM from intercepting the shared ECDH secret, LED blinks (to be entered by hand on the 2FA device) are included in key creation. Watch for future tutorial videos for details. 2FA is used to verify that the correct transaction is signed even when using a fully compromised host computer. A verification key is generated during the factory installation and can be updated at any time by an owner. The verification message can be displayed and checked on a separate device (i.e. smartphone app or web service) that knows the verification key. The AES-256-CBC algorithm is used for encryption.
"device" : "lock"	"device" : { "lock" : "boolean" }	Disables `backup`, `verifypass`, and `seed` commands. These can be re-enabled only after a `reset` command. Be sure to backup your wallet before locking the device! The `verifypass` command allows a second object to be used for verification. If a thief steals an unlocked BitBox and knows its password, the coins can be taken without the need for the second object. The `lock` command adds full 2FA protection by requiring the thief to also possess the second object in order to steal coins. After locking the BitBox, a single-use 4-digit PIN is included within the encrypted verification message and is displayed on the second object. This PIN is required to unlock (i.e. decrypt) the signed transaction before it is broadcast to the Bitcoin network.
Reset
"reset" : "__ERASE__"	"reset" : "success"	Factory resets the wallet and erases all wallet data. U2F second-factor authentication data is NOT reset.
"reset" : "U2F"	"reset" : "success"	DEPRECATED. Use `{seed: {source: U2F_create}}` to reset the U2F key.
Name the device
"name" : "name"	"name" : "name"	Saves a new `name`. Long names are truncated to 31 characters. Sending an empty string will return the current name.
Blink the LED
"led" : "mode"	"led" : "success"	`mode` is `blink` or `abort`. The latter reproduces the LED blinks that occur when a user aborts an operation that requires touch confirmation.
Get a random number from the device
"random" : "mode"	"random" : "number"	Mode: `true` or `pseudo`. A 16 byte random number is returned as a hexadecimal string. The hardware random number generator (RNG) on a high-security crypto chip is used. The true RNG mode updates a seed value written to the chip's EEPROM, which has a specified minimum lifespan of 100,000 write cycles. The pseudo RNG mode derives numbers using this seed and does not affect lifespan.
Get an extended public key at the indicated keypath
"xpub" : "keypath"	"xpub" : "xpub" "echo" : "encrypted_xpub"	Returns the `xpub` for the given `keypath`, for example, `m/purpose'/coin_type'/account'/change/address_index`, following the BIP44 standard. An apostrophe designates a hardened key derivation. A letter `p`, `h`, or `H` can be used instead of an apostrophe. In practice, the BitBox wallet is agnostic of the keypath, i.e., `m/index_1/index_2/index_3/...index_N` is valid for a varying number of N indices. Each index can be designated as hardened or not. The `echo` returns the extended public key encrypted using the 2FA verification key.
Set access to the bootloader
"bootloader" : "status"	"bootloader" : "status"	`status` is `lock` or `unlock`. When unlocked, the bootloader is entered by pressing the touch button within 3 seconds of plugging in the device. Otherwise, the firmware starts.
Get device information
"device" : "info"	"device" : { "seeded" : "boolean", "name" : "name", "U2F" : "boolean", "lock" : "boolean", "sdcard" : "boolean", "new_hidden_wallet" : "boolean", "bootlock" : "boolean", "version" : "version", "U2F_hijack" : "boolean", "serial" : "number", "id" : "sha(xpub)" }	`id` is a SHA256 hash of the master extended public key if seeded.
Feature options
"feature_set" : { "U2F" : "boolean", "U2F_hijack" : "boolean", "new_hidden_wallet" : "boolean" }	"feature_set" : "success"	`U2F` enables or disables the U2F second-factor authentication function. If disabled, any U2F commands will be answered with a device busy error message. Enabled by default on factory reset. `U2F_hijack` enables or disables browser access to the hardware wallet API. Communication is done by hijacking the 'key handle' data field of the U2F authentication command. This must be enabled to use any web integrations, such as MyEtherWallet. If `U2F` is disabled, `U2F_hijack` will also be disabled, even if it is set to be enabled. When disabled, any U2F hijack commands will be answered with a device busy error message. Enabled by default on factory reset. `new_hidden_wallet` is enabled by default. Disabling it activates the deprecated legacy hidden wallet mode (added to make migration easier). boolean should be `true` or `false` and without quotes. A single feature or any combination of features can be sent.

API documentation

Version: 5.0.0