Files
brk/packages/brk_client/DOCS.md
2026-04-22 22:29:43 +02:00

40 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 80-byte block header.

Mempool.space docs

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

get_block_raw

def get_block_raw(hash: BlockHash) -> str

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_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_by_index

def get_tx_by_index(index: TxIndex) -> str

Txid by index.

Retrieve the transaction ID (txid) at a given global transaction index. Returns the txid as plain text.

Endpoint: GET /api/tx-index/{index}

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) -> str

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

list_urpd_cohorts

def list_urpd_cohorts() -> List[Cohort]

Available URPD cohorts.

Cohorts for which URPD data is available. Returns names like all, sth, lth, utxos_under_1h_old.

Endpoint: GET /api/urpd

get_urpd

def get_urpd(cohort: Cohort, agg: Optional[UrpdAggregation] = None) -> Urpd

Latest URPD.

URPD for the most recent available date in the cohort. The response's date field echoes which date was served.

See the URPD tag description for the response shape and agg options.

Endpoint: GET /api/urpd/{cohort}

list_urpd_dates

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

Available URPD dates.

Dates for which a URPD snapshot is available for the cohort. One entry per UTC day, sorted ascending.

Endpoint: GET /api/urpd/{cohort}/dates

get_urpd_at

def get_urpd_at(cohort: Cohort,
                date: str,
                agg: Optional[UrpdAggregation] = None) -> Urpd

URPD at date.

URPD for a (cohort, date) pair. Returns { cohort, date, aggregation, close, total_supply, buckets } where each bucket is { price_floor, supply, realized_cap, unrealized_pnl }.

See the URPD tag description for unit conventions and agg options.

Endpoint: GET /api/urpd/{cohort}/{date}

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 (Child Pays For Parent) transaction, including the effective fee rate of the package.

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) -> List[BlockFeeRatesEntry]

Block fee rates.

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 total fees per block 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 coinbase reward (subsidy + fees) per block 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. Returns isvalid: false with an error message for invalid addresses.

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