This page describes documentation specific to the Bitcoin ChainDriver named as CosmosDriver created by the Blockin team.

Installation and Initialization

First, npm install blockin-btc-driver

Then, import via import BtcDriver from 'blockin-btc-driver';

To initialize a new instance, run:

const CosmosDriver = new CosmosDriver(CHAIN_ID);


See here for an example of implementing signatures in a compatible format using Phantom wallet.

const getProvider = () => {
  if ('phantom' in window) {
    const phantomWindow = window as any;
    const provider = phantomWindow.phantom?.bitcoin;
    if (provider?.isPhantom) {
      return provider;
    }'', '_blank');

function bytesToBase64(bytes: Uint8Array) {
  const binString = String.fromCodePoint(...bytes);
  return btoa(binString);

const signChallenge = async (message: string) => {
  const encodedMessage = new TextEncoder().encode(message);
  const provider = bitcoinProvider;
  const { signature } = await provider.signMessage(address, encodedMessage);

  return { message: message, signature: bytesToBase64(signature) };


This driver is compatible with BitBadges and querying badge ownership.

Note to use the BitBadges API and query badges, you must set a valid environment variable for process.env.BITBADGES_API_KEY.


For BitBadges, we use the collection ID the collectionId.

BitBadges assetIds must be in the form of [{ start: 1, end: 10 }, ....]

ownershipTimes (if blank, we query current time) can either be a valid JS Date string or in UNIX milliseconds via [{ start: 1, end: 1000000 }]

  collectionId: 1,
  assetIds: [{ start: 1, end: 1 }],
  mustOwnAmounts: [{ start: 0, end: 0 }],
  chain: 'BitBadges',

Ownership Times

For BitBadges, we support checking ownership time via their time-based balances feature. Note this is an ownership rights feature, it queries if the user has ownership rights for time XYZ currently, not that they had rights at time XYZ for time XYZ. See here.

To actually query if they owned at the current time, you must query the blockchain state at that time or provide a snapshot of it at that time. This is not supported currently.


You can provide snapshots for BitBadges badges via the verifyChallenge options. Snapshot maps are expected to be in the form of OffChainBalancesMap<NumberType>. See

Last updated