39 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_cost_basis_cohorts
- get_cost_basis_dates
- get_cost_basis
- 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
- get_tx_hex
- get_tx_merkle_proof
- get_tx_merkleblock_proof
- get_tx_outspend
- get_tx_outspends
- get_tx_raw
- get_tx_status
- 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 block header.
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.
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_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, log100value: 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.
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) -> List[float]
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
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 transaction.
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) -> 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
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
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
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.
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