40 KiB
Table of Contents
- brk_client
- BrkError
- BrkClient
- 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__
- series_endpoint
- index_to_date
- date_to_index
- get_api
- get_address
- get_address_txs
- get_address_confirmed_txs
- get_address_mempool_txs
- get_address_utxos
- get_block_by_height
- get_block
- get_block_header
- get_block_raw
- get_block_status
- get_block_txid
- get_block_txids
- get_block_txs
- get_block_txs_from_index
- get_blocks
- get_block_tip_hash
- get_block_tip_height
- get_blocks_from_height
- get_mempool
- get_live_price
- get_mempool_recent
- get_mempool_txids
- get_series_tree
- get_series_bulk
- get_series_count
- get_indexes
- list_series
- search_series
- get_series_info
- get_series
- get_series_data
- get_series_latest
- get_series_len
- get_series_version
- get_disk_usage
- get_sync_status
- get_tx_by_index
- get_tx
- get_tx_hex
- get_tx_merkle_proof
- get_tx_merkleblock_proof
- get_tx_outspend
- get_tx_outspends
- get_tx_raw
- get_tx_status
- list_urpd_cohorts
- get_urpd
- list_urpd_dates
- get_urpd_at
- get_block_v1
- get_blocks_v1
- get_blocks_v1_from_height
- get_cpfp
- get_difficulty_adjustment
- get_mempool_blocks
- get_precise_fees
- get_recommended_fees
- get_historical_price
- get_block_fee_rates
- get_block_fees
- get_block_rewards
- get_block_sizes_weights
- get_block_by_timestamp
- get_difficulty_adjustments
- get_difficulty_adjustments_by_period
- get_hashrate
- get_pools_hashrate
- get_pools_hashrate_by_period
- get_hashrate_by_period
- get_pool
- get_pool_blocks
- get_pool_blocks_from
- get_pool_hashrate
- get_pools
- get_pool_stats
- get_reward_stats
- get_prices
- get_transaction_times
- validate_address
- get_health
- get_openapi
- get_version
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).
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Endpoint: GET /api/blocks
get_block_tip_hash
def get_block_tip_hash() -> str
Block tip hash.
Returns the hash of the last block.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
Endpoint: GET /api/tx/{txid}/outspends
get_tx_raw
def get_tx_raw(txid: Txid) -> str
Transaction raw.
Returns a transaction as binary data.
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.
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.
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.
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.
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.
Endpoint: GET /api/v1/cpfp/{txid}
get_difficulty_adjustment
def get_difficulty_adjustment() -> DifficultyAdjustment
Difficulty adjustment.
Get current difficulty adjustment progress and estimates.
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.
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.
Endpoint: GET /api/v1/fees/precise
get_recommended_fees
def get_recommended_fees() -> RecommendedFees
Recommended fees.
Get recommended fee rates for different confirmation targets.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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