0.15.0 • Public • Published

BitBox02 Logo

BitBox02 JavaScript library

The JavaScript library is compiled from bitbox02-api-go using GopherJS.

Given that it contains the full client implementation compiled from Go, the library is quite large (~3MB). We recommend lazy-loading it only when necessary.


The BitBox02 is a hardware wallet made by Shift Crypto that simplifies secure handling of crypto coins through storing private keys and signing transactions.


To enable communication from the browser to the BitBox02, either:

  • WebHID needs to be supported by the browser, e.g. Chrome
  • or the BitBoxBridge needs to be installed and running

When integrating the BitBox02 into your application, your domain needs to be whitelisted in the BitBoxBridge. To do so, please submit a Pull Request or an Issue in the bitbox-bridge repository. Localhost is already whitelisted, so you can develop locally.

The BitBox02 Javascript library is available as NPM package bitbox02-api.


$ npm install bitbox02-api


import { BitBox02API, getDevicePath} from 'bitbox02-api';


To get the device path, the BitBoxBridge needs to be running. If WebHID (navigator.hid) is available, getDevicePath() returns "WEBHID", which instructs BitBox02API to prefer WebHID over the BitBoxBridge.

const devicePath = await getDevicePath();
const BitBox02 = new BitBox02API(devicePath);

Connect to device

The BitBox02API.connect() method takes 5 arguments:

 * @param showPairingCb Callback that is used to show pairing code. Must not block.
 * @param userVerify Promise that should resolve once the user wants to continue.
 * @param handleAttastionCb Callback that should handle the bool attestation result. Must not block.
 * @param onCloseCb Callback that's called when the websocket connection is closed.
 * @param setStatusCb Callback that lets the API set the status received from the device.
 * @return Promise that will resolve once the pairing is complete.
connect (showPairingCb, userVerify, handleAttestationCb, onCloseCb, setStatusCb)

Check BitBox02 edition

The BitBox02 is available in two editions: "Multi" and "Bitcoin-only". To check what edition is used, e.g. to make sure that Ethereum functionality is supported, use the following function.

import { constants } from 'bitbox02-api';

BitBox02.firmware().Product() === constants.Product.BitBox02Multi
BitBox02.firmware().Product() === constants.Product.BitBox02BTCOnly


All available methods are documented in docs/

Sample integration

This is a sample BitBox02Wallet class integration for connecting to the BitBox02 device using the BitBoxBridge and this JS API. See sandbox/src/index.js for a fully functional sandbox implementation.

import {
} from 'bitbox02-api';

class BitBox02 {
  constructor(logout) {  // You can provide the `logout` callback of your application in the constructor
    this.logout = logout;
    this.status = undefined;
    this.pairingConfirmed = false;

  async init(keypath) {
    try {
      const devicePath = await getDevicePath();
      this.api = new BitBox02API(devicePath);

      await this.api.connect(

        /** @param showPairingCb
         *  Store the pairing code on the class instance. Show this to the user to compare with code
         *  on the device when `this.status === 'unpaired'`
        pairingCode => {
          this.pairingCode = pairingCode;

        /** @param userVerify
         *  Store the Promise's `resolve` on the class instance to call when the user clicks the corresponding button
         *  in your application after confirming the pairing on device
        async () => {
          return new Promise(resolve => {
            this.pairingConfirmed = true;
            this.pairingConfirmationResolve = resolve;

        /** @param handleAttestationCb
        *  Store the attestation result on the class instance. If attestation fails, the user might have a fake device.
        *  Handle this condition below.
        attestationResult => {
          this.attestation = attestationResult;

        /** @param onCloseCb
        *  Log the user out of your application when device is unplugged/the websocket closes.
        *  Here we use the `logout` function provided in the constructor as the callback.
        () => {

        /** @param setStatusCb
        *  Store the status on the class instance to take appropriate actions based on status.
        *  All possible status can be found here:
        status => {
          this.status = status;
    } catch(e) {

    switch (this.api.firmware().Product()) {
        case constants.Product.BitBox02Multi:
            console.log("This is a BitBox02 Multi");
        case constants.Product.BitBox02BTCOnly:
            console.log("This is a BitBox02 BTC-only");

    // Handle attestattion failure
    if (!this.attestation) {
      alert('Attestation failed');


const device = new BitBox02(yourLogoutFunction)
await device.init()

// Now you can call any of the supported API methods documented above e.g.:
const ethPub = await device.api.ethGetRootPubKey("m/44'/60'/0'/0");

Local development

To compile the library using GopherJS, run the following commands:

$ make dockerinit
$ make dockercompile

To simply run the demo sandbox implementation, run the following command and visit http://localhost:8000.

$ make builddemo
$ make servedemo


npm i bitbox02-api

DownloadsWeekly Downloads






Unpacked Size

7.21 MB

Total Files


Last publish


  • benmma
  • 2ndthat