Bitcoin API

Bitcoin has two entry points.

With the subpath you can assemble everything a payment needs using the SDK alone. Three address types are supported.

Import

import {
  BitcoinApp,
  BTC_MAINNET_PATH,
  BTC_TESTNET_PATH,
  type BtcMessageSignature,
  type InputSigningPath,
} from '@openloop/sdk-core'

import {
  scanAccount,
  selectUtxos,
  buildPsbt,
  extractRawTx,
  broadcastTx,
  BtcError,
  type BtcNetwork,
  type BtcAccount,
} from '@openloop/sdk-core/bitcoin'

Signature verification (verifyBtcMessage / verifyBtcPsbt) lives in a separate subpath, @openloop/sdk-core/verify (Signature Verification).

BitcoinApp

Initialization

import { BitcoinApp } from '@openloop/sdk-core'

const btc = new BitcoinApp(transport)

transport is any transport instance that implements the ITransport interface.

Methods

Every method takes the transport’s exclusive lock (lock() / unlock()) while it runs.

Paths can be passed as "84'/0'/0'/0/0" or "m/84'/0'/0'/0/0". The only hardened marker is ' (h is not accepted).

getAddress

Retrieves a bech32 (P2WPKH) address.

async getAddress(testnet?: boolean): Promise<{
  publicKey: string   // uncompressed public key (hex, 65 bytes)
  address: string     // bech32 address ("bc1..." or "tb1...")
  chainCode: string   // chain code (hex, 32 bytes)
}>

Parameters

Default Paths

Example

// Mainnet
const { address } = await btc.getAddress()
// address: "bc1q..."

// Testnet
const { address: testnetAddress } = await btc.getAddress(true)
// testnetAddress: "tb1q..."

getAddressWithPath

Retrieves an address at an arbitrary BIP32 path. Use it for multi-account setups and for change addresses.

async getAddressWithPath(path: string): Promise<{
  publicKey: string   // uncompressed public key (hex, 65 bytes)
  address: string
  chainCode: string
}>

The current firmware returns a bech32 (P2WPKH) address regardless of the path’s purpose (44' / 49' / 84'). The network follows the second path element (coin type): 1' gives tb1…, anything else gives bc1…. When you need a Legacy (P2PKH) or Nested SegWit (P2SH-P2WPKH) address, fetch the account’s extended public key with getExtendedPubkey and derive it with the subpath’s deriveAddresses.

Example

// First address of the second account
const second = await btc.getAddressWithPath("84'/0'/1'/0/0")

// Change address
const change = await btc.getAddressWithPath("84'/0'/0'/1/0")

// The "m/" prefix is also accepted
const sixth = await btc.getAddressWithPath("m/84'/0'/0'/0/5")

getAccountXpub

Retrieves the account-level public key and chain code (m/84'/coin'/0'). The path is fixed: only BIP-84 account 0 can be retrieved. When you need Legacy (44'), Nested SegWit (49'), or account 1 and later, use getExtendedPubkey.

async getAccountXpub(coinType: number): Promise<{
  publicKey: string   // compressed public key (hex, 33 bytes)
  chainCode: string   // chain code (hex, 32 bytes)
}>

Parameters

Example

const { publicKey, chainCode } = await btc.getAccountXpub(0)  // mainnet

The return value does not include depth or the parent fingerprint, so it cannot be passed to the subpath’s deriveAddresses (a BtcXpub is required). If the device’s response is not 65 bytes, it throws an Error.

getExtendedPubkey

Retrieves the extended public key at an arbitrary path (GET_EXTENDED_PUBKEY of the Ledger Bitcoin v2 protocol; CLA 0xE1 / INS 0x00). The returned BtcXpub can be passed directly to the subpath’s deriveAddresses / scanAccount / findAddressPath.

async getExtendedPubkey(path: string, display?: boolean): Promise<BtcXpub>

interface BtcXpub {
  publicKey: string         // compressed public key (hex, 33 bytes)
  chainCode: string         // chain code (hex, 32 bytes)
  parentFingerprint: number // fingerprint of the immediate parent (not the master)
  depth: number             // number of levels from m
  xpub: string              // the serialized string ("xpub…" / "tpub…")
}

Parameters

Validation

The SDK checks that the device’s answer belongs to the path you asked for. It throws an Error if any of the following disagrees.

• depth does not match the number of levels requested
• The last element (child number) does not match
• The coin type (second element) is 1 but the key is not a tpub, or it is anything else but the key is not an xpub (paths with fewer than two elements are not checked)

Paths longer than 10 levels, and elements that cannot be read as numbers, are also rejected with an Error before anything is sent to the device.

Firmware requirement and the returned form

• Firmware 0.63.125 or later returns an extended public key that is correct as BIP-32. The command is available from 0.63.122, but there the parent fingerprint was wrong (fixed in 0.63.125). The published firmware (the v1.1 series) satisfies this.
• The version bytes depend only on the coin type (the second element) and do not look at the purpose. For 44’ and 49’ paths as well, the returned string has the xpub / tpub prefix (not ypub / zpub, the same as Ledger’s protocol v2).
• Paths go up to 10 levels, and there is no restriction on the purpose.

Example

import { accountPathOf } from '@openloop/sdk-core/bitcoin'

// Extended public key for Native SegWit, account 0, testnet ("m/84'/1'/0'")
const xpub = await btc.getExtendedPubkey(accountPathOf({ script: 'p2wpkh', account: 0 }, 'testnet4'))
console.log(xpub.xpub.slice(0, 4), xpub.depth) // "tpub" 3

▲ An extended public key lets anyone derive every address the account will ever create. Do not let the receiving side leak it.

The SDK also exposes the following (from @openloop/sdk-core).

getMasterFingerprint

Retrieves the wallet’s BIP32 master key fingerprint — hash160(master public key)[:4]. It is identical to the value the device computes internally, and it is the value to set in a PSBT input’s BIP32 derivation (master_fingerprint).

async getMasterFingerprint(): Promise<string>  // 8 lowercase hex characters (big-endian), e.g. "631698e0"

When to Use It

In a normal wallet integration you fetch this value once, at account import time, and embed it in the input derivations of every PSBT you build afterwards. It matters most on the AirGap / watch-only (QR PSBT) path: the device decides an input is its own by matching this fingerprint, so a PSBT input without the correct master_fingerprint is treated as belonging to another wallet and cannot be signed — there is no input-path injection there like signPsbtWithPaths over USB.

Internally it fetches the public key at depth 0 (master m) and returns the first 4 bytes of its hash160. This is the same processing Sparrow / HWI perform.

Example

const fp = await btc.getMasterFingerprint()  // e.g. "631698e0"

// Embed it in the PSBT input's BIP32 derivation (type 0x06):
//   value = fingerprint(4B) ‖ path(4B LE × N)

signMessage

Signs a message in BIP-137 format.

async signMessage(
  message: string,
  path: string
): Promise<BtcMessageSignature>

Parameters

Returns: BtcMessageSignature

The SDK adjusts v to match the path’s purpose (first element). On every route (USB / BLE / WalletConnect, and so on) the header is one that external verifiers accept.

If the device’s response is not 65 bytes, it throws an Error. If the user rejects, it throws an ApduError (0x6985).

Example

const sig = await btc.signMessage('Hello, Bitcoin!', BTC_MAINNET_PATH)
console.log(sig.v)         // 39–42 (BTC_MAINNET_PATH is 84')
console.log(sig.signature) // Base64 encoded signature

signPsbt

Signs a PSBT (Partially Signed Bitcoin Transaction). The paths are detected automatically from the BIP32_DERIVATION fields inside the PSBT.

async signPsbt(psbt: Uint8Array | string): Promise<Uint8Array>

Parameters

Returns

The signed PSBT as binary data (Uint8Array). After signing, the device finalizes the inputs (FINAL_SCRIPTSIG / FINAL_SCRIPTWITNESS) and returns them, so the result can go straight to extractRawTx (after converting to hex).

Errors

The SDK does not limit the number of inputs. If you exceed the device’s limit (for example 32 inputs for the whole PSBT), the device refuses and you get an ApduError.

The BtcError thrown by BitcoinApp is the same class as the BtcError imported from @openloop/sdk-core/bitcoin (0.8.1 and later; recognise it with instanceof BtcError. On 0.8.0 and earlier it is a different class, so branch on e.name === 'BtcError' and e.code).

import { BtcError } from '@openloop/sdk-core/bitcoin'

try {
  await btc.signPsbt('70736274ff...')
} catch (e) {
  if (e instanceof BtcError) {
    console.log(e.code) // 'psbt_too_large'
  }
}

signPsbtHex

PSBT signing with hex strings — both input and output are hex strings (the output has no 0x prefix).

async signPsbtHex(psbt: string): Promise<string>

Example

const signedHex = await btc.signPsbtHex('70736274ff...')

signPsbtWithPaths

Signs a PSBT with the BIP32 path of each input given explicitly. Use it when the PSBT has no BIP32_DERIVATION fields, or when you want to sign only specific inputs. The paths returned by the subpath’s buildPsbt can be passed straight in as the second argument.

async signPsbtWithPaths(
  psbt: string,
  inputPaths: InputSigningPath[]
): Promise<string>

Parameters

The return value is the signed PSBT as a hex string (no 0x). As with signPsbt, it is already finalized.

A signature with explicit paths is limited to 10 inputs on the current device. Beyond that the device refuses and you get an ApduError.

InputSigningPath

Example

const signedHex = await btc.signPsbtWithPaths('70736274ff...', [
  { index: 0, path: "84'/0'/0'/0/0" },
  { index: 1, path: "84'/0'/0'/0/3" },
  { index: 2, path: "84'/0'/0'/1/0" }, // change
])

@openloop/sdk-core/bitcoin

A set of functions that assemble everything around a payment without touching the device. The SDK has no UI and no default servers, so it keeps to three rules.

• No state. Network, endpoints, timeouts, account, and cache are all passed as arguments.
• No wording. Errors come back as a BtcError code (an English message is attached, but branch on code). The caller decides what to show on screen.
• A failed fetch is never treated as empty. When the endpoints cannot be reached, it stops with fetch_failed (it will never read “balance 0” and build a payment).

The fragments below assume the following variables are already defined.

import { BitcoinApp, type ITransport } from '@openloop/sdk-core'
import {
  accountPathOf,
  createAddressCache,
  scanAccount,
  type BtcNetwork,
  type BtcAccount,
} from '@openloop/sdk-core/bitcoin'

declare const transport: ITransport // a connected transport

const btc = new BitcoinApp(transport)

// The caller chooses the endpoints (the SDK has no defaults)
const net: BtcNetwork = {
  id: 'testnet4',
  esplora: ['https://mempool.space/testnet4/api'],
  feeEndpoints: ['https://mempool.space/testnet4/api'],
  timeoutMs: 15_000,
}
const acct: BtcAccount = { script: 'p2wpkh', account: 0 }

// Fetch the account's extended public key from the device just once
const xpub = await btc.getExtendedPubkey(accountPathOf(acct, net.id))

// Scan the account to get the UTXOs and the next change address
const cache = createAddressCache()
const { utxos, nextChange } = await scanAccount(xpub, acct, net, { cache })

Types

type BtcNetworkId = 'mainnet' | 'testnet3' | 'testnet4'
type BtcScript = 'p2pkh' | 'p2sh-p2wpkh' | 'p2wpkh'

interface BtcNetwork {
  id: BtcNetworkId
  esplora: string[]       // base URLs of Esplora-compatible APIs, tried best first
  feeEndpoints: string[]  // endpoints that serve `/v1/fees/recommended` (mempool.space compatible)
  timeoutMs: number       // timeout of one call in milliseconds, including reading the body
}

interface BtcAccount {
  script: BtcScript       // determines the purpose (44' / 49' / 84')
  account: number         // the account number (hardened)
}

interface BtcUtxo {
  txid: string
  vout: number
  value: number           // sats
  address: string
  path: string            // e.g. "m/84'/1'/0'/0/3"
  publicKey: string       // compressed public key (hex, 33 bytes)
  confirmed: boolean      // false below 1 confirmation
  blockHeight?: number
}

type BtcAddressKind = 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr'

• Testnet3 and Testnet4 have the same addresses; only the endpoints differ (the coin type is 1 for both).
• BtcXpub is the return type of getExtendedPubkey.
• The purpose follows from script and the coin type from id, so BtcAccount does not carry them (see PURPOSE_OF_SCRIPT / COIN_TYPE_OF_NETWORK).

Function Overview

The BIP-32 helpers (deriveChildPublicKey and others) and the constants are covered below.

pathOf

function pathOf(acct: BtcAccount, net: BtcNetworkId, change: 0 | 1, index: number): string
function accountPathOf(acct: BtcAccount, net: BtcNetworkId): string

import { pathOf, accountPathOf } from '@openloop/sdk-core/bitcoin'

pathOf({ script: 'p2wpkh', account: 0 }, 'testnet4', 1, 3)   // "m/84'/1'/0'/1/3"
pathOf({ script: 'p2pkh', account: 1 }, 'mainnet', 0, 0)     // "m/44'/0'/1'/0/0"
accountPathOf({ script: 'p2sh-p2wpkh', account: 0 }, 'mainnet') // "m/49'/0'/0'"

An unknown script / net, a non-integer or out-of-range account / index, or a change other than 0 / 1 throws a BtcError (bad_argument).

publicKeyToAddress

function publicKeyToAddress(publicKey: string, script: BtcScript, net: BtcNetworkId): string

Builds the address of each type from a compressed public key (hex, 33 bytes, starting with 02 / 03; a 0x prefix is accepted).

import { publicKeyToAddress } from '@openloop/sdk-core/bitcoin'

const compressed = '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
publicKeyToAddress(compressed, 'p2wpkh', 'mainnet')       // "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
publicKeyToAddress(compressed, 'p2pkh', 'mainnet')        // "1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH"
publicKeyToAddress(compressed, 'p2sh-p2wpkh', 'testnet4') // "2NAUYAHhujozruyzpsFRP63mbrdaU5wnEpN"

A string that is not a compressed public key (including an uncompressed 65-byte key) throws a BtcError (bad_argument). The publicKey returned by getAddress is uncompressed, so it cannot be passed in as is.

deriveAddresses

function deriveAddresses(
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetworkId,
  change: 0 | 1,
  from: number,
  count: number
): Array<{ address: string; path: string; publicKey: string }>

Derives count addresses of the change chain starting at index from, from the account’s extended public key. It does not touch the device.

• xpub must be a BtcXpub at the account level (m/purpose'/coin'/account', depth is 3). A different depth would silently build the addresses of another account, so it is rejected with a BtcError (bad_argument).
• from / count are integers of 0 or more (an empty array is returned when count is 0). Otherwise bad_argument.
• In the return value, path has the form "m/84'/1'/0'/0/5" and publicKey is the compressed public key (hex).

import { deriveAddresses } from '@openloop/sdk-core/bitcoin'

const receive = deriveAddresses(xpub, acct, net.id, 0, 0, 5) // receiving 0-4
console.log(receive[0].address, receive[0].path)             // "tb1q…" "m/84'/1'/0'/0/0"

validateAddress

function validateAddress(address: string, net: BtcNetworkId): { kind: BtcAddressKind }

Validates a destination address. It reads all three formats — bech32, bech32m, and base58check — and checks the network (so a testnet address can never receive real coins).

Because invalid_address and network_mismatch are reported separately, you can offer “switch networks?” only for the latter.

import { validateAddress, BtcError } from '@openloop/sdk-core/bitcoin'

try {
  const { kind } = validateAddress('tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', 'mainnet')
  console.log(kind)
} catch (e) {
  if (e instanceof BtcError && e.code === 'network_mismatch') {
    console.log('This is an address for another network')
  }
}

addressToScriptPubKey

function addressToScriptPubKey(address: string, net: BtcNetworkId): Uint8Array

Turns an address into a scriptPubKey. It performs the same checks as validateAddress first, so it throws the same codes (invalid_address / network_mismatch).

encodeSegwitAddress / decodeSegwitAddress

function encodeSegwitAddress(hrp: string, version: number, program: Uint8Array): string
function decodeSegwitAddress(address: string): { hrp: string; version: number; program: Uint8Array }

Encodes a witness address (bech32 for v0, bech32m for v1 and later) and decodes one while verifying the checksum. All-uppercase addresses are accepted; mixed case is rejected. They throw a plain Error, not a BtcError.

createAddressCache

function createAddressCache(): BtcAddressCache

interface BtcAddressCache {
  get(address: string): { path: string; publicKey: string } | undefined
  set(address: string, entry: { path: string; publicKey: string }): void
  syncToDevice(deviceId: string | null): void
  readonly size: number
  clear(): void
}

A cache of address → path/public key. It is not one per module: the caller owns it (so you can keep separate caches per network, type, and account). Pass it to scanAccount and findAddressPath and they remember the addresses they derive.

syncToDevice(deviceId) declares which device owns the cache. When the owner changes, everything is discarded (treating another device’s addresses as your own would hand out paths that cannot be signed). The same non-null ID does nothing. null (owner unknown) discards everything every time.

cache.syncToDevice('device-A')
cache.set('tb1q…', { path: "m/84'/1'/0'/0/0", publicKey: '02…' })
cache.syncToDevice('device-B') // the owner changed → everything is discarded
console.log(cache.size)        // 0

findAddressPath

function findAddressPath(
  address: string,
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetworkId,
  cache?: BtcAddressCache,
  opts?: { maxIndex?: number; step?: number }
): string | null

Looks up the path for an address. It checks cache first; if the address is not there it derives step addresses at a time (default 20), receiving chain first and then the change chain, from 0 up to maxIndex - 1 (default 200). The addresses it derives along the way are stored in cache.

It returns null when nothing is found (it does not throw — an address that is not yours is not an error). A maxIndex / step below 1 or not an integer, or an empty address, throws a BtcError (bad_argument).

import { findAddressPath } from '@openloop/sdk-core/bitcoin'

const path = findAddressPath(nextChange.address, xpub, acct, net.id, cache)
// e.g. "m/84'/1'/0'/1/0"; null when not found

scanAccount

function scanAccount(
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetwork,
  opts?: {
    cache?: BtcAddressCache
    gapLimit?: number      // default 20
    concurrency?: number   // default 4 (API_PARALLEL_LIMIT)
    knownUsed?: Array<{ chain: 0 | 1; index: number }>  // indexes the caller already knows were used
  } & FetchDeps
): Promise<BtcScanResult>

interface BtcScanResult {
  used: Array<{ address: string; path: string }>  // addresses that have been used (both chains)
  utxos: BtcUtxo[]
  nextChange: { index: number; address: string; path: string; publicKey: string }
}

Scans the account. It examines both the receiving chain and the change chain until gapLimit unused addresses in a row, and queries UTXOs only for addresses that have a balance.

• nextChange is the first index with no transactions on the change chain. It can be passed straight to buildPsbt’s change (so addresses are not reused).
• If even one address cannot be queried on any endpoint, it does not assume the address is unused and stops with fetch_failed.
• bad_argument if xpub.depth is not 3. bad_argument also if gapLimit / concurrency is below 1 or not an integer.
• The returned utxos include unconfirmed ones (confirmed: false).
• opts.knownUsed (Array<{ chain: 0 | 1; index: number }>): indexes the caller already knows were used. They are counted as used even if the endpoint says unused (they enter used, the gap is counted again, and nextChange skips them). The test networks (Testnet3 / 4) share keys, so you can pass the indexes used on the other network. The endpoint is still queried, so balances remain the endpoint’s answer. Omit it and nothing changes; an invalid entry is bad_argument.

import { scanAccount } from '@openloop/sdk-core/bitcoin'

const { used, utxos, nextChange } = await scanAccount(xpub, acct, net, { cache, gapLimit: 20 })
const total = utxos.reduce((sum, u) => sum + u.value, 0)
console.log(`${used.length} used addresses, balance ${total} sats`)
console.log('Next change destination', nextChange.address, nextChange.path)

addressStats

function addressStats(
  address: string,
  net: BtcNetwork,
  deps?: FetchDeps
): Promise<BtcAddressStats>

interface BtcAddressStats {
  txCount: number   // Number of transactions (confirmed + unconfirmed). Greater than 0 means "used"
  funded: number    // Total received (sats, confirmed + unconfirmed)
  spent: number     // Total spent (sats, confirmed + unconfirmed). Balance is funded - spent
}

Asks the endpoint (Esplora address) whether one address has been used. It is for callers that have only the addresses a wallet returned (for example over WalletConnect) and no extended public key, so scanAccount is not available, and that want to pick a change address with no transactions.

• A missing field, a non-integer, or a negative value is never read as 0; it fails that endpoint (and fetch_failed when every endpoint fails).
• An address that does not fit net is refused before any endpoint is queried (invalid_address / network_mismatch).

fetchUtxos

function fetchUtxos(
  addresses: Array<{ address: string; path: string; publicKey: string }>,
  net: BtcNetwork,
  deps?: FetchDeps
): Promise<BtcUtxo[]>

Collects all the UTXOs of the given addresses (at most API_PARALLEL_LIMIT at a time). If even one address fails on every endpoint, it throws fetch_failed. The shape of each answer (txid, vout, amount) is checked, and an answer with the wrong shape counts as that endpoint failing and moves on to the next. bad_argument if addresses is not an array.

import { fetchUtxos, deriveAddresses } from '@openloop/sdk-core/bitcoin'

const firstFive = deriveAddresses(xpub, acct, net.id, 0, 0, 5)
const found = await fetchUtxos(firstFive, net)

fetchPrevTx

function fetchPrevTx(txid: string, net: BtcNetwork, deps?: FetchDeps): Promise<string>

Fetches the raw hex (lowercase) of a previous transaction. A Legacy (P2PKH) input reads its amount from the whole previous transaction, so buildPsbt needs it.

import { fetchPrevTx } from '@openloop/sdk-core/bitcoin'

const prevTxHex = await fetchPrevTx(utxos[0].txid, net)

getFeeRate

function getFeeRate(net: BtcNetwork, deps?: FetchDeps): Promise<number>

Fetches the fee rate (sat/vB): the halfHourFee of /v1/fees/recommended on feeEndpoints (this is specific to mempool.space and separate from the Esplora endpoints).

A value that arrives from outside is never used as is: anything outside MIN_FEE_RATE_SAT_VB (1) to MAX_FEE_RATE_SAT_VB (5000) is not rounded but rejected with a BtcError (fee_rate_out_of_range). fetch_failed when it cannot be fetched, and bad_argument when net.feeEndpoints is empty.

import { getFeeRate } from '@openloop/sdk-core/bitcoin'

const feeRate = await getFeeRate(net) // e.g. 5

selectUtxos

function selectUtxos(
  utxos: BtcUtxo[],
  opts: {
    to: BtcRecipient[]            // { address: string; value: number }[], at least one
    feeRate: number               // sat/vB
    script: BtcScript             // input type (one type per account)
    net: BtcNetworkId
    excluded?: Iterable<string>   // used-up markers "txid:vout"
    changeAddress?: string        // change destination, used to estimate the output size
  }
): BtcSelection

interface BtcSelection {
  inputs: BtcUtxo[]
  fee: number      // the fee actually paid (sats) = total in − total out
  change: number   // change (sats). 0 means no change output is created
  vbytes: number   // estimated size (vB)
}

Selects which UTXOs to spend.

• Only confirmed UTXOs (confirmed: true) are candidates. Your own change is not used either until it has a confirmation. UTXOs whose "txid:vout" is in excluded are also left out.
• Largest first (ties by txid, then vout), adding until the shortfall is covered. It never refuses on the number of inputs (anything above the limit is refused by the device at signing time).
• The fee is ceil(vbytes × feeRate). The size is estimated from the input type, the destination types, and the change output (estimateVbytes). If you omit changeAddress, the change is counted as the same type as the inputs.
• If the change is below DUST_SATS (546), no output is created and it is added to the fee (change is 0, and fee is total in − amount sent).

import { selectUtxos, getFeeRate } from '@openloop/sdk-core/bitcoin'

const sel = selectUtxos(utxos, {
  to: [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 20_000 }],
  feeRate: await getFeeRate(net),
  script: acct.script,
  net: net.id,
  excluded: new Set<string>(),
  changeAddress: nextChange.address,
})
console.log(sel.inputs.length, sel.fee, sel.change, sel.vbytes)

estimateVbytes

function estimateVbytes(numInputs: number, script: BtcScript, outputVbytes: number[]): number

Estimates the transaction size (vB) as ceil(TX_OVERHEAD_VBYTES + number of inputs × INPUT_VBYTES[script] + sum of output vB). Pass the output vB values from OUTPUT_VBYTES (per destination type). An unknown script throws bad_argument.

import { estimateVbytes, OUTPUT_VBYTES } from '@openloop/sdk-core/bitcoin'

// 2 P2WPKH inputs, 1 P2WPKH destination + 1 change output
estimateVbytes(2, 'p2wpkh', [OUTPUT_VBYTES.p2wpkh, OUTPUT_VBYTES.p2wpkh]) // 209

buildPsbt

function buildPsbt(args: {
  script: BtcScript
  net: BtcNetworkId
  inputs: BtcPsbtInput[]
  to: Array<{ address: string; value: number }>
  change?: BtcChangeOutput   // omit when no change output is created
}): BtcPsbt

interface BtcPsbtInput extends BtcUtxo {
  prevTxHex?: string         // required only for Legacy ('p2pkh')
}
interface BtcChangeOutput {  // scanAccount's nextChange plus a value
  address: string
  path: string
  publicKey: string
  value: number
}
interface BtcPsbt {
  psbtHex: string
  paths: Array<{ index: number; path: string }>   // can be passed straight to signPsbtWithPaths
}

Builds a PSBT (v0). The transaction version is 2, locktime is 0, and every input’s sequence is RBF_SEQUENCE (0xfffffffd), so RBF (fee bumping) is possible.

• The fingerprint in BIP32_DERIVATION is 00000000. Specify the paths by passing the returned paths to signPsbtWithPaths.
• An input’s scriptPubKey is built from publicKey, not from address.
• The change output also gets a BIP32_DERIVATION. The device matches it against its own keys and does not show the change as a “destination”.
• For Legacy, prevTxHex is checked against txid before it is used.

It does not refuse in advance because of the size of what it built. A PSBT that is too large is refused by the device.

import { buildPsbt } from '@openloop/sdk-core/bitcoin'

const to = [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 20_000 }]
const { psbtHex, paths } = buildPsbt({
  script: acct.script,
  net: net.id,
  inputs: sel.inputs,
  to,
  change: sel.change > 0 ? { ...nextChange, value: sel.change } : undefined,
})

For Legacy, fetch the previous transaction for each input and pass it in.

import { fetchPrevTx, buildPsbt, type BtcAccount } from '@openloop/sdk-core/bitcoin'

const legacyAcct: BtcAccount = { script: 'p2pkh', account: 0 }
const withPrev = await Promise.all(
  sel.inputs.map(async u => ({ ...u, prevTxHex: await fetchPrevTx(u.txid, net) }))
)
const legacy = buildPsbt({
  script: legacyAcct.script,
  net: net.id,
  inputs: withPrev,
  to: [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 20_000 }],
})

extractRawTx

function extractRawTx(signedPsbtHex: string): { rawTxHex: string; txid: string }

Extracts the broadcastable raw transaction and its txid from a signed PSBT (the return value of signPsbtWithPaths / signPsbtHex). It handles all three types and reads each input’s FINAL_SCRIPTSIG (0x07) and FINAL_SCRIPTWITNESS (0x08). If even one input has a witness, it uses the form with marker and flag (BIP-144). It does not verify signatures.

A PSBT that cannot be read (magic bytes missing, truncated, or an input that is not finalized) throws a BtcError (bad_psbt); a string that is not hex throws bad_argument.

import { extractRawTx } from '@openloop/sdk-core/bitcoin'

const { rawTxHex, txid } = extractRawTx(signedHex)

broadcastTx

function broadcastTx(
  rawTxHex: string,
  net: BtcNetwork,
  expectedTxid?: string,
  deps?: FetchDeps
): Promise<string>   // txid

Broadcasts a raw transaction with POST /tx and returns the txid. It tries the endpoints best first and does not resend to another endpoint once one has accepted (so it is never broadcast twice).

• If an answer is not shaped like a txid, it counts as that endpoint failing and moves on (so a captive portal’s 200 <html> is never returned as a txid).
• Always pass expectedTxid (the txid returned by extractRawTx). When you do, two things take effect:
  • An endpoint answer meaning “already in the mempool” or “already in a block” is treated as success, and expectedTxid is returned (this is the answer you get when the same transaction is sent again).
  • If the txid an endpoint returns differs from expectedTxid, it throws bad_response.

import { broadcastTx } from '@openloop/sdk-core/bitcoin'

const sentTxid = await broadcastTx(rawTxHex, net, txid)

BtcError

class BtcError extends OpenloopError {
  readonly code: BtcErrorCode
}

type BtcErrorCode =
  | 'bad_argument' | 'invalid_address' | 'network_mismatch'
  | 'fetch_failed' | 'bad_response'
  | 'prev_tx_too_large' | 'fee_rate_out_of_range'
  | 'insufficient' | 'insufficient_unconfirmed' | 'fee_too_high' | 'fee_exceeds_amount'
  | 'psbt_too_large' | 'bad_psbt' | 'broadcast_rejected'

code is the key to branch on. Messages are in English, and the SDK carries no translations.

FetchDeps and Retries

The functions that query endpoints (opts of scanAccount; deps of fetchUtxos / fetchPrevTx / getFeeRate / broadcastTx) accept an extra argument of this shape.

interface FetchDeps {
  fetchImpl?: typeof fetch   // default: the runtime's globalThis.fetch
  retryDelayMs?: number      // interval between retries (ms). Default API_RETRY_DELAY_MS (1000)
  retryCount?: number        // attempts per URL. Default API_RETRY_COUNT (3)
}

Endpoints are tried from the first entry of esplora (or feeEndpoints) onward, each URL up to retryCount times. The first answer that is HTTP 200 and has the expected shape is returned. If every endpoint fails, it throws fetch_failed. In a runtime without fetch, you need fetchImpl.

import { getFeeRate } from '@openloop/sdk-core/bitcoin'

const fetchImpl: typeof fetch = (url, init) => fetch(url, init) // e.g. to inject measurement or a proxy
const rate = await getFeeRate(net, { fetchImpl, retryCount: 1, retryDelayMs: 0 })

Constants

All are importable from @openloop/sdk-core/bitcoin.

BIP-32 Helpers

Child derivation from public keys alone, and reading and writing extended public keys. They can be imported from both @openloop/sdk-core and @openloop/sdk-core/bitcoin (the same implementation, re-exported).

Private keys are not handled (hardened derivation is not possible). Invalid input throws a plain Error.

Sending a Transaction End to End

Combining the functions above gives the following (Native SegWit, testnet4).

import { BitcoinApp, type ITransport } from '@openloop/sdk-core'
import {
  BtcError,
  accountPathOf,
  broadcastTx,
  buildPsbt,
  createAddressCache,
  extractRawTx,
  getFeeRate,
  scanAccount,
  selectUtxos,
  validateAddress,
  type BtcAccount,
  type BtcNetwork,
} from '@openloop/sdk-core/bitcoin'

const net: BtcNetwork = {
  id: 'testnet4',
  esplora: ['https://mempool.space/testnet4/api'],
  feeEndpoints: ['https://mempool.space/testnet4/api'],
  timeoutMs: 15_000,
}
const acct: BtcAccount = { script: 'p2wpkh', account: 0 }

async function send(transport: ITransport, toAddress: string, sats: number): Promise<string> {
  const btc = new BitcoinApp(transport)

  validateAddress(toAddress, net.id)                           // check the destination and network

  const xpub = await btc.getExtendedPubkey(accountPathOf(acct, net.id))
  const cache = createAddressCache()
  const { utxos, nextChange } = await scanAccount(xpub, acct, net, { cache })

  const sel = selectUtxos(utxos, {
    to: [{ address: toAddress, value: sats }],
    feeRate: await getFeeRate(net),
    script: acct.script,
    net: net.id,
    changeAddress: nextChange.address,
  })

  const { psbtHex, paths } = buildPsbt({
    script: acct.script,
    net: net.id,
    inputs: sel.inputs,
    to: [{ address: toAddress, value: sats }],
    change: sel.change > 0 ? { ...nextChange, value: sel.change } : undefined,
  })

  const signedHex = await btc.signPsbtWithPaths(psbtHex, paths) // review and approve on the device
  const { rawTxHex, txid } = extractRawTx(signedHex)
  return broadcastTx(rawTxHex, net, txid)
}

async function main(transport: ITransport) {
  try {
    const txid = await send(transport, 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', 20_000)
    console.log('Broadcast', txid)
  } catch (e) {
    if (e instanceof BtcError) {
      console.log(e.code, e.message) // e.g. 'insufficient'
    } else {
      throw e // ApduError (rejection, etc.), TransportError
    }
  }
}

Signature Verification

Verifies a signature returned by the device with a reference implementation (@noble). It lives in the @openloop/sdk-core/verify subpath and does not depend on the transport. The full list is in the API Reference.

Both return a VerifyResult ({ recovered: string; expected?: string; ok: boolean }).

verifyBtcMessage

function verifyBtcMessage(message: string, sig: BtcMessageSignature, identity: string): VerifyResult

Recovers the public key from the sig returned by signMessage and compares it with identity. identity is a public key (hex, compressed 33 bytes or uncompressed 65 bytes) or an address. An address can be matched only when it carries the hash160 of the public key (bech32 P2WPKH and base58 P2PKH); a P2SH-P2WPKH address (the hash160 of the redeem script) does not match. In that case pass the public key. A broken signature returns ok: false instead of throwing.

import { verifyBtcMessage } from '@openloop/sdk-core/verify'

const message = 'Hello, Bitcoin!'
const sig = await btc.signMessage(message, BTC_MAINNET_PATH)
const { address } = await btc.getAddress()
const result = verifyBtcMessage(message, sig, address)
console.log(result.ok) // true

verifyBtcPsbt

function verifyBtcPsbt(signedPsbtHex: string): VerifyResult

Verifies the signatures of a signed PSBT (such as the return value of signPsbtHex) by recomputing the signature hash. Three input types can be verified.

ok tells whether the signature is cryptographically valid. The public key is read from inside the PSBT and put in expected. An input of any other type, or a PSBT whose shape cannot be read, throws an exception.

import { verifyBtcPsbt } from '@openloop/sdk-core/verify'

const signedHex = await btc.signPsbtHex('70736274ff...')
const result = verifyBtcPsbt(signedHex)
console.log(result.ok)

PSBT Protocol Details

PSBT signing is a three-phase exchange with the device (CLA 0xF0).

Phase 1: Sending the PSBT

• One APDU carries at most 250 bytes of data. When the PSBT fits in the first chunk, the data of the final chunk is empty.
• num_paths=0: detected automatically from BIP32_DERIVATION inside the PSBT
• num_paths>0: the path for each input is given explicitly ([1B input_index][1B path_len][4B * path_len elements], each element big-endian, hardened is 0x80000000)

Phase 2: Signing on the Device

The user reviews the transaction details on the device screen and presses the approve button. If the user rejects, it becomes an ApduError (0x6985). After signing, the device finalizes the inputs and holds the PSBT.

Phase 3: Retrieving the Signed PSBT

Increment the chunk index (P1) from 0 and repeat until 0x9000 comes back. The transport does not throw on 0x61XX; it returns it as the last two bytes of the response. The SDK takes a trailing 0x61XX to mean more data follows, strips those two bytes, and concatenates the chunks.

A chunk is 250 bytes (PSBT_RESPONSE_CHUNK_SIZE) and P1 is one byte, so at most 256 chunks (MAX_SIGNED_PSBT_BYTES = 64,000 bytes) can be read. Beyond that it stops with a BtcError (psbt_too_large).

bitcoinjs-lib Integration

Sign a PSBT built with bitcoinjs-lib. The PSBT the device returns is already finalized, so do not call finalizeAllInputs() (it would fail with Can not finalize input); call extractTransaction() directly.

import * as bitcoin from 'bitcoinjs-lib'
import { BitcoinApp, BTC_MAINNET_PATH, type ITransport } from '@openloop/sdk-core'

async function signWithBitcoinjs(transport: ITransport): Promise<string> {
  const btc = new BitcoinApp(transport)

  // Get the address
  const { address } = await btc.getAddress()

  // Build the PSBT
  const psbt = new bitcoin.Psbt({ network: bitcoin.networks.bitcoin })
  psbt.addInput({
    hash: '7d067b4a697a09d2c3cff7d4d9506c9955e93bff41bf82d439da7d030382bc3e',
    index: 0,
    witnessUtxo: {
      script: bitcoin.address.toOutputScript(address, bitcoin.networks.bitcoin),
      value: 50000,
    },
  })
  psbt.addOutput({
    address: 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4',
    value: 40000,
  })

  // Sign the PSBT on the device
  const psbtHex = psbt.toHex()
  const signedHex = await btc.signPsbtWithPaths(psbtHex, [
    { index: 0, path: BTC_MAINNET_PATH },
  ])

  // Load the signed (already finalized) PSBT and extract the raw transaction to broadcast
  const signedPsbt = bitcoin.Psbt.fromHex(signedHex)
  return signedPsbt.extractTransaction().toHex()
}

With the subpath’s buildPsbt / extractRawTx you can do the same without bitcoinjs-lib (Sending a Transaction End to End).

Next Steps

• Solana API
• Error Handling — handling rejections and busy devices