Crate brk_server 

brk_server

HTTP API server for Bitcoin on-chain analytics.

Features

• OpenAPI spec: Auto-generated docs at /api with full spec at /openapi.json
• LLM-optimized: Compact spec at /api.json for AI tools
• Response caching: ETag-based with LRU cache (1000 entries by default, configurable via ServerConfig::cache_size)
• Compression: Brotli, gzip, deflate, zstd
• Static files: Optional web interface hosting

Usage

let server = Server::new(
    &async_query,
    ServerConfig {
        data_path,
        website: Website::Filesystem(files_path),
        ..Default::default()
    },
);
server.serve(None).await?;

Endpoints

Path	Description
/api	Interactive API documentation
/openapi.json	Full OpenAPI specification
/api.json	Compact OpenAPI for LLMs
/api/address/{address}	Address stats, transactions, UTXOs
/api/block/{hash}	Block info, transactions, status
/api/block-height/{height}	Block by height
/api/tx/{txid}	Transaction details, status, hex
/api/mempool	Fee estimates, mempool stats
/api/metrics	Metric catalog and data queries
/api/v1/mining/...	Hashrate, difficulty, pools

Caching

ETag-based revalidation. Five strategies pick the etag scheme:

• Tip: chain-state, etag = tip hash prefix (invalidates per block + reorgs)
• Immutable: deeply-confirmed data, etag = format version
• BlockBound: data tied to a specific block hash (reorg-safe)
• Deploy: catalog/static data, etag = build version
• MempoolHash: mempool data, etag = projected next-block hash

Browser sees Cache-Control: public, no-cache, stale-if-error=86400 (always revalidate, ETag makes it cheap). CDN sees a separate CDN-Cache-Control directive whose stable tier is selected by CdnCacheMode (Live revalidates every request; Aggressive caches up to a year as immutable and requires a purge on deploy).

Configuration

Binds to port 3110, auto-incrementing up to 3210 if busy.

Dependencies

• brk_query - data access
• aide + axum - HTTP routing and OpenAPI
• tower-http - compression and tracing

Structs

Error

Server error type that maps to HTTP status codes and structured JSON.

Port

Server port. Defaults to 3110.

Server

ServerConfig

Server-wide configuration set at startup.

Enums

CdnCacheMode

CDN caching strategy for stable responses (immutable / deploy / block-bound / historical series). Live-tier responses (Tip, MempoolHash, tail series) are unaffected.

Website

Website configuration:

Constants

DEFAULT_MAX_UTXOS

Default max UTXOs returned per address. Bounds worst-case work and response size, prevents heavy-address DDoS.

DEFAULT_MAX_WEIGHT

Default max series-query response weight. 50 MB - generous enough for any honest query, low enough to limit cache-buster leverage.

VERSION

Traits

ApiRoutes

Functions

finish_openapi

Finalize a router and extract the OpenAPI spec.

Type Aliases

Result

Server result type with Error that implements IntoResponse.