Files
brk/packages/brk_client/DOCS.md
2026-04-01 22:16:40 +02:00

39 KiB

Table of Contents

brk_client

BrkError Objects

class BrkError(Exception)

Custom error class for BRK client errors.

BrkClient Objects

class BrkClient(BrkClientBase)

Main BRK client with series tree and API methods.

VERSION

INDEXES

POOL_ID_TO_POOL_NAME

TERM_NAMES

EPOCH_NAMES

CLASS_NAMES

SPENDABLE_TYPE_NAMES

AGE_RANGE_NAMES

UNDER_AGE_NAMES

OVER_AGE_NAMES

AMOUNT_RANGE_NAMES

OVER_AMOUNT_NAMES

UNDER_AMOUNT_NAMES

PROFITABILITY_RANGE_NAMES

PROFIT_NAMES

LOSS_NAMES

__init__

def __init__(base_url: str = 'http://localhost:3000', timeout: float = 30.0)

series_endpoint

def series_endpoint(series: str, index: Index) -> SeriesEndpoint[Any]

Create a dynamic series endpoint builder for any series/index combination.

Use this for programmatic access when the series name is determined at runtime. For type-safe access, use the series tree instead.

index_to_date

def index_to_date(index: Index, i: int) -> Union[date, datetime]

Convert an index value to a date/datetime for date-based indexes.

date_to_index

def date_to_index(index: Index, d: Union[date, datetime]) -> int

Convert a date/datetime to an index value for date-based indexes.

get_api

def get_api() -> str

Compact OpenAPI specification.

Compact OpenAPI specification optimized for LLM consumption. Removes redundant fields while preserving essential API information. Full spec available at /openapi.json.

Endpoint: GET /api.json

get_address

def get_address(address: Addr) -> AddrStats

Address information.

Retrieve address information including balance and transaction counts. Supports all standard Bitcoin address types (P2PKH, P2SH, P2WPKH, P2WSH, P2TR).

Mempool.space docs

Endpoint: GET /api/address/{address}

get_address_txs

def get_address_txs(address: Addr,
                    after_txid: Optional[Txid] = None) -> List[Transaction]

Address transactions.

Get transaction history for an address, sorted with newest first. Returns up to 50 mempool transactions plus the first 25 confirmed transactions. Use ?after_txid= for pagination.

Mempool.space docs

Endpoint: GET /api/address/{address}/txs

get_address_confirmed_txs

def get_address_confirmed_txs(address: Addr,
                              after_txid: Optional[Txid] = None
                              ) -> List[Transaction]

Address confirmed transactions.

Get confirmed transactions for an address, 25 per page. Use ?after_txid= for pagination.

Mempool.space docs

Endpoint: GET /api/address/{address}/txs/chain

get_address_mempool_txs

def get_address_mempool_txs(address: Addr) -> List[Txid]

Address mempool transactions.

Get unconfirmed transaction IDs for an address from the mempool (up to 50).

Mempool.space docs

Endpoint: GET /api/address/{address}/txs/mempool

get_address_utxos

def get_address_utxos(address: Addr) -> List[Utxo]

Address UTXOs.

Get unspent transaction outputs (UTXOs) for an address. Returns txid, vout, value, and confirmation status for each UTXO.

Mempool.space docs

Endpoint: GET /api/address/{address}/utxo

get_block_by_height

def get_block_by_height(height: Height) -> str

Block hash by height.

Retrieve the block hash at a given height. Returns the hash as plain text.

Mempool.space docs

Endpoint: GET /api/block-height/{height}

get_block

def get_block(hash: BlockHash) -> BlockInfo

Block information.

Retrieve block information by block hash. Returns block metadata including height, timestamp, difficulty, size, weight, and transaction count.

Mempool.space docs

Endpoint: GET /api/block/{hash}

get_block_header

def get_block_header(hash: BlockHash) -> str

Block header.

Returns the hex-encoded block header.

Mempool.space docs

Endpoint: GET /api/block/{hash}/header

get_block_raw

def get_block_raw(hash: BlockHash) -> List[float]

Raw block.

Returns the raw block data in binary format.

Mempool.space docs

Endpoint: GET /api/block/{hash}/raw

get_block_status

def get_block_status(hash: BlockHash) -> BlockStatus

Block status.

Retrieve the status of a block. Returns whether the block is in the best chain and, if so, its height and the hash of the next block.

Mempool.space docs

Endpoint: GET /api/block/{hash}/status

get_block_txid

def get_block_txid(hash: BlockHash, index: TxIndex) -> str

Transaction ID at index.

Retrieve a single transaction ID at a specific index within a block. Returns plain text txid.

Mempool.space docs

Endpoint: GET /api/block/{hash}/txid/{index}

get_block_txids

def get_block_txids(hash: BlockHash) -> List[Txid]

Block transaction IDs.

Retrieve all transaction IDs in a block. Returns an array of txids in block order.

Mempool.space docs

Endpoint: GET /api/block/{hash}/txids

get_block_txs

def get_block_txs(hash: BlockHash) -> List[Transaction]

Block transactions.

Retrieve transactions in a block by block hash. Returns up to 25 transactions starting from index 0.

Mempool.space docs

Endpoint: GET /api/block/{hash}/txs

get_block_txs_from_index

def get_block_txs_from_index(hash: BlockHash,
                             start_index: TxIndex) -> List[Transaction]

Block transactions (paginated).

Retrieve transactions in a block by block hash, starting from the specified index. Returns up to 25 transactions at a time.

Mempool.space docs

Endpoint: GET /api/block/{hash}/txs/{start_index}

get_blocks

def get_blocks() -> List[BlockInfo]

Recent blocks.

Retrieve the last 10 blocks. Returns block metadata for each block.

Mempool.space docs

Endpoint: GET /api/blocks

get_block_tip_hash

def get_block_tip_hash() -> str

Block tip hash.

Returns the hash of the last block.

Mempool.space docs

Endpoint: GET /api/blocks/tip/hash

get_block_tip_height

def get_block_tip_height() -> str

Block tip height.

Returns the height of the last block.

Mempool.space docs

Endpoint: GET /api/blocks/tip/height

get_blocks_from_height

def get_blocks_from_height(height: Height) -> List[BlockInfo]

Blocks from height.

Retrieve up to 10 blocks going backwards from the given height. For example, height=100 returns blocks 100, 99, 98, ..., 91. Height=0 returns only block 0.

Mempool.space docs

Endpoint: GET /api/blocks/{height}

get_mempool

def get_mempool() -> MempoolInfo

Mempool statistics.

Get current mempool statistics including transaction count, total vsize, total fees, and fee histogram.

Mempool.space docs

Endpoint: GET /api/mempool

get_live_price

def get_live_price() -> Dollars

Live BTC/USD price.

Returns the current BTC/USD price in dollars, derived from on-chain round-dollar output patterns in the last 12 blocks plus mempool.

Endpoint: GET /api/mempool/price

get_mempool_recent

def get_mempool_recent() -> List[MempoolRecentTx]

Recent mempool transactions.

Get the last 10 transactions to enter the mempool.

Mempool.space docs

Endpoint: GET /api/mempool/recent

get_mempool_txids

def get_mempool_txids() -> List[Txid]

Mempool transaction IDs.

Get all transaction IDs currently in the mempool.

Mempool.space docs

Endpoint: GET /api/mempool/txids

get_series_tree

def get_series_tree() -> TreeNode

Series catalog.

Returns the complete hierarchical catalog of available series organized as a tree structure. Series are grouped by categories and subcategories.

Endpoint: GET /api/series

get_series_bulk

def get_series_bulk(
        series: SeriesList,
        index: Index,
        start: Optional[RangeIndex] = None,
        end: Optional[RangeIndex] = None,
        limit: Optional[Limit] = None,
        format: Optional[Format] = None) -> Union[List[AnySeriesData], str]

Bulk series data.

Fetch multiple series in a single request. Supports filtering by index and date range. Returns an array of SeriesData objects. For a single series, use get_series instead.

Endpoint: GET /api/series/bulk

get_cost_basis_cohorts

def get_cost_basis_cohorts() -> List[str]

Available cost basis cohorts.

List available cohorts for cost basis distribution.

Endpoint: GET /api/series/cost-basis

get_cost_basis_dates

def get_cost_basis_dates(cohort: Cohort) -> List[Date]

Available cost basis dates.

List available dates for a cohort's cost basis distribution.

Endpoint: GET /api/series/cost-basis/{cohort}/dates

get_cost_basis

def get_cost_basis(cohort: Cohort,
                   date: str,
                   bucket: Optional[CostBasisBucket] = None,
                   value: Optional[CostBasisValue] = None) -> dict

Cost basis distribution.

Get the cost basis distribution for a cohort on a specific date.

Query params:

  • bucket: raw (default), lin200, lin500, lin1000, log10, log50, log100
  • value: supply (default, in BTC), realized (USD), unrealized (USD)

Endpoint: GET /api/series/cost-basis/{cohort}/{date}

get_series_count

def get_series_count() -> List[SeriesCount]

Series count.

Returns the number of series available per index type.

Endpoint: GET /api/series/count

get_indexes

def get_indexes() -> List[IndexInfo]

List available indexes.

Returns all available indexes with their accepted query aliases. Use any alias when querying series.

Endpoint: GET /api/series/indexes

list_series

def list_series(page: Optional[float] = None,
                per_page: Optional[float] = None) -> PaginatedSeries

Series list.

Paginated flat list of all available series names. Use page query param for pagination.

Endpoint: GET /api/series/list

search_series

def search_series(q: SeriesName, limit: Optional[Limit] = None) -> List[str]

Search series.

Fuzzy search for series by name. Supports partial matches and typos.

Endpoint: GET /api/series/search

get_series_info

def get_series_info(series: SeriesName) -> SeriesInfo

Get series info.

Returns the supported indexes and value type for the specified series.

Endpoint: GET /api/series/{series}

get_series

def get_series(series: SeriesName,
               index: Index,
               start: Optional[RangeIndex] = None,
               end: Optional[RangeIndex] = None,
               limit: Optional[Limit] = None,
               format: Optional[Format] = None) -> Union[AnySeriesData, str]

Get series data.

Fetch data for a specific series at the given index. Use query parameters to filter by date range and format (json/csv).

Endpoint: GET /api/series/{series}/{index}

get_series_data

def get_series_data(series: SeriesName,
                    index: Index,
                    start: Optional[RangeIndex] = None,
                    end: Optional[RangeIndex] = None,
                    limit: Optional[Limit] = None,
                    format: Optional[Format] = None) -> Union[List[bool], str]

Get raw series data.

Returns just the data array without the SeriesData wrapper. Supports the same range and format parameters as the standard endpoint.

Endpoint: GET /api/series/{series}/{index}/data

get_series_latest

def get_series_latest(series: SeriesName, index: Index) -> str

Get latest series value.

Returns the single most recent value for a series, unwrapped (not inside a SeriesData object).

Endpoint: GET /api/series/{series}/{index}/latest

get_series_len

def get_series_len(series: SeriesName, index: Index) -> float

Get series data length.

Returns the total number of data points for a series at the given index.

Endpoint: GET /api/series/{series}/{index}/len

get_series_version

def get_series_version(series: SeriesName, index: Index) -> Version

Get series version.

Returns the current version of a series. Changes when the series data is updated.

Endpoint: GET /api/series/{series}/{index}/version

get_disk_usage

def get_disk_usage() -> DiskUsage

Disk usage.

Returns the disk space used by BRK and Bitcoin data.

Endpoint: GET /api/server/disk

get_sync_status

def get_sync_status() -> SyncStatus

Sync status.

Returns the sync status of the indexer, including indexed height, tip height, blocks behind, and last indexed timestamp.

Endpoint: GET /api/server/sync

get_tx

def get_tx(txid: Txid) -> Transaction

Transaction information.

Retrieve complete transaction data by transaction ID (txid). Returns inputs, outputs, fee, size, and confirmation status.

Mempool.space docs

Endpoint: GET /api/tx/{txid}

get_tx_hex

def get_tx_hex(txid: Txid) -> str

Transaction hex.

Retrieve the raw transaction as a hex-encoded string. Returns the serialized transaction in hexadecimal format.

Mempool.space docs

Endpoint: GET /api/tx/{txid}/hex

get_tx_merkle_proof

def get_tx_merkle_proof(txid: Txid) -> MerkleProof

Transaction merkle proof.

Get the merkle inclusion proof for a transaction.

Mempool.space docs

Endpoint: GET /api/tx/{txid}/merkle-proof

get_tx_merkleblock_proof

def get_tx_merkleblock_proof(txid: Txid) -> str

Transaction merkleblock proof.

Get the merkleblock proof for a transaction (BIP37 format, hex encoded).

Mempool.space docs

Endpoint: GET /api/tx/{txid}/merkleblock-proof

get_tx_outspend

def get_tx_outspend(txid: Txid, vout: Vout) -> TxOutspend

Output spend status.

Get the spending status of a transaction output. Returns whether the output has been spent and, if so, the spending transaction details.

Mempool.space docs

Endpoint: GET /api/tx/{txid}/outspend/{vout}

get_tx_outspends

def get_tx_outspends(txid: Txid) -> List[TxOutspend]

All output spend statuses.

Get the spending status of all outputs in a transaction. Returns an array with the spend status for each output.

Mempool.space docs

Endpoint: GET /api/tx/{txid}/outspends

get_tx_raw

def get_tx_raw(txid: Txid) -> List[float]

Transaction raw.

Returns a transaction as binary data.

Mempool.space docs

Endpoint: GET /api/tx/{txid}/raw

get_tx_status

def get_tx_status(txid: Txid) -> TxStatus

Transaction status.

Retrieve the confirmation status of a transaction. Returns whether the transaction is confirmed and, if so, the block height, hash, and timestamp.

Mempool.space docs

Endpoint: GET /api/tx/{txid}/status

get_block_v1

def get_block_v1(hash: BlockHash) -> BlockInfoV1

Block (v1).

Returns block details with extras by hash.

Mempool.space docs

Endpoint: GET /api/v1/block/{hash}

get_blocks_v1

def get_blocks_v1() -> List[BlockInfoV1]

Recent blocks with extras.

Retrieve the last 10 blocks with extended data including pool identification and fee statistics.

Mempool.space docs

Endpoint: GET /api/v1/blocks

get_blocks_v1_from_height

def get_blocks_v1_from_height(height: Height) -> List[BlockInfoV1]

Blocks from height with extras.

Retrieve up to 10 blocks with extended data going backwards from the given height.

Mempool.space docs

Endpoint: GET /api/v1/blocks/{height}

get_cpfp

def get_cpfp(txid: Txid) -> CpfpInfo

CPFP info.

Returns ancestors and descendants for a CPFP transaction.

Mempool.space docs

Endpoint: GET /api/v1/cpfp/{txid}

get_difficulty_adjustment

def get_difficulty_adjustment() -> DifficultyAdjustment

Difficulty adjustment.

Get current difficulty adjustment progress and estimates.

Mempool.space docs

Endpoint: GET /api/v1/difficulty-adjustment

get_mempool_blocks

def get_mempool_blocks() -> List[MempoolBlock]

Projected mempool blocks.

Get projected blocks from the mempool for fee estimation.

Mempool.space docs

Endpoint: GET /api/v1/fees/mempool-blocks

get_precise_fees

def get_precise_fees() -> RecommendedFees

Precise recommended fees.

Get recommended fee rates with up to 3 decimal places.

Mempool.space docs

Endpoint: GET /api/v1/fees/precise

def get_recommended_fees() -> RecommendedFees

Recommended fees.

Get recommended fee rates for different confirmation targets.

Mempool.space docs

Endpoint: GET /api/v1/fees/recommended

get_historical_price

def get_historical_price(
        timestamp: Optional[Timestamp] = None) -> HistoricalPrice

Historical price.

Get historical BTC/USD price. Optionally specify a UNIX timestamp to get the price at that time.

Mempool.space docs

Endpoint: GET /api/v1/historical-price

get_block_fee_rates

def get_block_fee_rates(time_period: TimePeriod) -> str

Block fee rates (WIP).

Work in progress. Get block fee rate percentiles (min, 10th, 25th, median, 75th, 90th, max) for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/blocks/fee-rates/{time_period}

get_block_fees

def get_block_fees(time_period: TimePeriod) -> List[BlockFeesEntry]

Block fees.

Get average block fees for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/blocks/fees/{time_period}

get_block_rewards

def get_block_rewards(time_period: TimePeriod) -> List[BlockRewardsEntry]

Block rewards.

Get average block rewards (coinbase = subsidy + fees) for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/blocks/rewards/{time_period}

get_block_sizes_weights

def get_block_sizes_weights(time_period: TimePeriod) -> BlockSizesWeights

Block sizes and weights.

Get average block sizes and weights for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/blocks/sizes-weights/{time_period}

get_block_by_timestamp

def get_block_by_timestamp(timestamp: Timestamp) -> BlockTimestamp

Block by timestamp.

Find the block closest to a given UNIX timestamp.

Mempool.space docs

Endpoint: GET /api/v1/mining/blocks/timestamp/{timestamp}

get_difficulty_adjustments

def get_difficulty_adjustments() -> List[DifficultyAdjustmentEntry]

Difficulty adjustments (all time).

Get historical difficulty adjustments including timestamp, block height, difficulty value, and percentage change.

Mempool.space docs

Endpoint: GET /api/v1/mining/difficulty-adjustments

get_difficulty_adjustments_by_period

def get_difficulty_adjustments_by_period(
        time_period: TimePeriod) -> List[DifficultyAdjustmentEntry]

Difficulty adjustments.

Get historical difficulty adjustments for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y.

Mempool.space docs

Endpoint: GET /api/v1/mining/difficulty-adjustments/{time_period}

get_hashrate

def get_hashrate() -> HashrateSummary

Network hashrate (all time).

Get network hashrate and difficulty data for all time.

Mempool.space docs

Endpoint: GET /api/v1/mining/hashrate

get_pools_hashrate

def get_pools_hashrate() -> List[PoolHashrateEntry]

All pools hashrate (all time).

Get hashrate data for all mining pools.

Mempool.space docs

Endpoint: GET /api/v1/mining/hashrate/pools

get_pools_hashrate_by_period

def get_pools_hashrate_by_period(
        time_period: TimePeriod) -> List[PoolHashrateEntry]

All pools hashrate.

Get hashrate data for all mining pools for a time period. Valid periods: 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/hashrate/pools/{time_period}

get_hashrate_by_period

def get_hashrate_by_period(time_period: TimePeriod) -> HashrateSummary

Network hashrate.

Get network hashrate and difficulty data for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/hashrate/{time_period}

get_pool

def get_pool(slug: PoolSlug) -> PoolDetail

Mining pool details.

Get detailed information about a specific mining pool including block counts and shares for different time periods.

Mempool.space docs

Endpoint: GET /api/v1/mining/pool/{slug}

get_pool_blocks

def get_pool_blocks(slug: PoolSlug) -> List[BlockInfoV1]

Mining pool blocks.

Get the 10 most recent blocks mined by a specific pool.

Mempool.space docs

Endpoint: GET /api/v1/mining/pool/{slug}/blocks

get_pool_blocks_from

def get_pool_blocks_from(slug: PoolSlug, height: Height) -> List[BlockInfoV1]

Mining pool blocks from height.

Get 10 blocks mined by a specific pool before (and including) the given height.

Mempool.space docs

Endpoint: GET /api/v1/mining/pool/{slug}/blocks/{height}

get_pool_hashrate

def get_pool_hashrate(slug: PoolSlug) -> List[PoolHashrateEntry]

Mining pool hashrate.

Get hashrate history for a specific mining pool.

Mempool.space docs

Endpoint: GET /api/v1/mining/pool/{slug}/hashrate

get_pools

def get_pools() -> List[PoolInfo]

List all mining pools.

Get list of all known mining pools with their identifiers.

Mempool.space docs

Endpoint: GET /api/v1/mining/pools

get_pool_stats

def get_pool_stats(time_period: TimePeriod) -> PoolsSummary

Mining pool statistics.

Get mining pool statistics for a time period. Valid periods: 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y

Mempool.space docs

Endpoint: GET /api/v1/mining/pools/{time_period}

get_reward_stats

def get_reward_stats(block_count: float) -> RewardStats

Mining reward statistics.

Get mining reward statistics for the last N blocks including total rewards, fees, and transaction count.

Mempool.space docs

Endpoint: GET /api/v1/mining/reward-stats/{block_count}

get_prices

def get_prices() -> Prices

Current BTC price.

Returns bitcoin latest price (on-chain derived, USD only).

Mempool.space docs

Endpoint: GET /api/v1/prices

get_transaction_times

def get_transaction_times() -> List[float]

Transaction first-seen times.

Returns timestamps when transactions were first seen in the mempool. Returns 0 for mined or unknown transactions.

Mempool.space docs

Endpoint: GET /api/v1/transaction-times

validate_address

def validate_address(address: str) -> AddrValidation

Validate address.

Validate a Bitcoin address and get information about its type and scriptPubKey.

Mempool.space docs

Endpoint: GET /api/v1/validate-address/{address}

get_health

def get_health() -> Health

Health check.

Returns the health status of the API server, including uptime information.

Endpoint: GET /health

get_openapi

def get_openapi() -> str

OpenAPI specification.

Full OpenAPI 3.1 specification for this API.

Endpoint: GET /openapi.json

get_version

def get_version() -> str

API version.

Returns the current version of the API server

Endpoint: GET /version