Class: BitcoinConnection

Defined in: packages/bitcoin/src/connection.ts:50

Represents a connection to a single Bitcoin network. Holds the REST and optional RPC clients for that network.

The underlying clients use a sans-I/O protocol layer that separates request construction from HTTP execution. By default, requests are executed via the global fetch function. Supply a custom HttpExecutor to use any HTTP client.

Example

// Quick setup with defaults (uses fetch)
const btc = BitcoinConnection.forNetwork('regtest');

// With a custom HTTP executor
const btc = BitcoinConnection.forNetwork('testnet4', {
  rest: { host: 'https://my-mempool/api' },
  executor: myCustomExecutor,
});

// Direct usage
const tx = await btc.rest.transaction.get(txid);
const block = await btc.rpc?.getBlock({ height: 100 });

// Sans-I/O: build requests without performing I/O
const req = btc.rest.protocol.getTx(txid);
const res = await myHttpClient.execute(req);

Constructors

Constructor

new BitcoinConnection(options): BitcoinConnection

Defined in: packages/bitcoin/src/connection.ts:63

Parameters

options

BitcoinConnectionOptions

Returns

BitcoinConnection

Properties

data

readonly data: Network

Defined in: packages/bitcoin/src/connection.ts:61

bitcoinjs-lib network data (for address derivation, PSBT signing, etc.).

---

name

readonly name: NetworkName

Defined in: packages/bitcoin/src/connection.ts:52

The network this connection targets.

---

rest

readonly rest: BitcoinRestClient

Defined in: packages/bitcoin/src/connection.ts:55

REST client (Esplora API).

---

rpc?

readonly optional rpc?: BitcoinCoreRpcClient

Defined in: packages/bitcoin/src/connection.ts:58

RPC client (Bitcoin Core). May be undefined if not configured.

Methods

btcToSats()

static btcToSats(btc): number

Defined in: packages/bitcoin/src/connection.ts:113

Converts Bitcoin (BTC) to satoshis. Uses string-based arithmetic to avoid floating-point precision errors.

Parameters

btc

number

Returns

number

Throws

If the value has more than 8 decimal places.

---

forNetwork()

static forNetwork(network, overrides?): BitcoinConnection

Defined in: packages/bitcoin/src/connection.ts:79

Create a connection for a single network with optional REST/RPC endpoint overrides. Merges overrides on top of defaults from DEFAULT_BITCOIN_NETWORK_CONFIG. Does not read environment variables.

Parameters

network

NetworkName

The network name (e.g., 'regtest', 'testnet4', 'bitcoin').

overrides?

Optional endpoint and executor overrides.

executor?

HttpExecutor

rest?

Partial<RestConfig>

rpc?

RpcConfig

Returns

BitcoinConnection

A BitcoinConnection for the requested network.

---

satsToBtc()

static satsToBtc(sats): number

Defined in: packages/bitcoin/src/connection.ts:128

Converts satoshis to Bitcoin (BTC). Uses string-based arithmetic to avoid floating-point precision errors.

Parameters

sats

number

Must be a non-negative integer.

Returns

number