API Docs

Backend explorer API reference

Loading grouped routes, DTO contracts, response rules, and endpoint details for the explorer backend.

Explorer Home

Explore the Bdtcoin Explorer network in real time

Loading blocks, transactions, mempool activity, miners, and supply data from the live network.

API Docs

Backend explorer API reference

A frontend-facing reference for the live explorer contract: grouped backend routes, same-origin compatibility aliases, query and path parameters, DTO shapes, transport behavior, and shared error responses.

Route groups

Grouped by service responsibility so related DTOs stay together.

Total endpoints

Includes health, explorer JSON routes, same-origin text aliases, analytics, and streaming transport.

JSON responses

Routes returning standard application/json envelopes or singleton DTOs.

Text responses

Legacy-compatible same-origin aliases returning plain-text coin values.

Streaming routes

Current realtime transport exposed as server-sent events.

Shared contracts and response rules

These rules appear across multiple handlers and are useful before you inspect the individual route cards.

Shared error response

Most backend failures return the same JSON error envelope.

Transport: application/json
Payload: single top-level error message string
Used for 400 validation failures, 404 misses, and 500 service failures

{
  "error": "failed to load blocks"
}

Shared list response shape

List-style endpoints reuse the frontend paging contract validated by Zod.

items: array payload
pagination.limit / pagination.offset when paging applies
filters.from / filters.to / filters.range / filters.interval on series-style endpoints
meta.lastUpdated may appear when a route supplies extra metadata

{
  "items": [],
  "pagination": { "limit": 20, "offset": 0 },
  "filters": { "range": "30d", "interval": "day" }
}

Units and conventions

Bdtcoin Explorer uses backend-native atomic units and UTC-oriented timestamps.

Balance and supply fields ending in Sats are atomic units and may be formatted as BDTC in the frontend.
Fee-rate analytics use jus/vB.
Dates in query strings use YYYY-MM-DD and timestamps return ISO-style strings in UTC context.

Plain-text compatibility routes

Some same-origin frontend aliases intentionally return text/plain instead of JSON for legacy compatibility.

GET /api/unmined-coins, /api/circulating-supply, /api/max-supply, and /api/total-supply return a plain-text string body.
These compatibility values are returned in BDTC, not atomic units.
Each alias is backed by the canonical GET /api/v1/supply payload and extracts one scalar field.

Streaming transport

The live event stream is the realtime transport in the public surface.

GET /api/v1/live/events/stream returns text/event-stream
The server emits named events every five seconds after an initial retry hint
Current event names are summary, mempool_summary, and blocks

retry: 5000

event: summary
data: {...}

event: blocks
data: {...}

Jump to route group

Use these anchors to scan by domain instead of scrolling through the entire API surface.

Service and health

Top-level availability and identity routes outside the /api/v1 explorer namespace.

Blocks

Canonical block listing, detail, latest-block lookup, and block-scoped transaction history.

Transactions

Transaction detail, confirmation status, and raw-hex access.

Addresses

Address detail plus related transaction, UTXO, and balance-history routes.

Holders and labels

Holder leaderboards, distribution views, snapshots, and locked-allocation labeling.

Live and mempool

Realtime explorer snapshots, stream transport, mempool state, and mempool analytics.

Miners and whale analytics

Miner production datasets and whale-transfer analytics endpoints.

Market and supply

Supply state, distribution buckets, and market summary pricing signals.

Network stats

Overview totals plus transaction, address, mining, fee, and block series analytics.

Exact-match search resolution and live suggestion APIs used by the explorer search experience.

Service and health

3 endpoints

Service and health

Top-level availability and identity routes outside the /api/v1 explorer namespace.

GET

Service root

Returns a minimal backend identity payload for quick smoke checks.

ServiceStatusResponse

JSON

ServiceStatusResponse

Simple service metadata object.

Top-level fields

servicestatus

Success example

{
  "service": "bdtexplorer",
  "status": "ok"
}

Error responses

No explicit error branch is documented for this route in the handler.

GET

/health/live

Liveness probe

Reports process liveness and uptime details.

HealthStatus

JSON

HealthStatus

Health payload used by liveness checks.

Top-level fields

statusappNamestartedAtuptimecheckedAt

Success example

{
  "status": "ok",
  "appName": "bdtexplorer-frontend",
  "startedAt": "2026-03-19T20:00:00Z",
  "uptime": "2026-03-19T20:00:00Z",
  "checkedAt": "2026-03-19T20:00:00Z"
}

Error responses

No explicit error branch is documented for this route in the handler.

GET

/health/ready

Readiness probe

Reports readiness with the same shape as the liveness probe.

HealthStatus

JSON

HealthStatus

Health payload used by readiness checks.

Top-level fields

statusappNamestartedAtuptimecheckedAt

Success example

{
  "status": "ok",
  "appName": "bdtexplorer-frontend",
  "startedAt": "2026-03-19T20:00:00Z",
  "uptime": "2026-03-19T20:00:00Z",
  "checkedAt": "2026-03-19T20:00:00Z"
}

Error responses

No explicit error branch is documented for this route in the handler.

Blocks

4 endpoints

Blocks

Canonical block listing, detail, latest-block lookup, and block-scoped transaction history.

GET

/api/v1/blocks

List blocks

Returns canonical blocks ordered newest first.

BlockListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

BlockListResponse

Paginated block list.

Top-level fields

items[]: BlockSummarypagination.limitpagination.offset

Item details

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "items": [
    {
      "height": 0,
      "hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "version": 0,
      "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
      "time": "2026-03-19T20:00:00Z",
      "medianTime": "2026-03-19T20:00:00Z",
      "nonce": 0,
      "bits": 0,
      "difficulty": 0,
      "sizeBytes": 0,
      "weight": 0,
      "txCount": 0,
      "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load blocks

{
  "error": "failed to load blocks"
}

GET

/api/v1/blocks/latest

Latest block

Fetches the current tip block as a singleton response.

BlockSummary

JSON

BlockSummary

Latest canonical block.

Top-level fields

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "height": 0,
  "hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "version": 0,
  "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
  "time": "2026-03-19T20:00:00Z",
  "medianTime": "2026-03-19T20:00:00Z",
  "nonce": 0,
  "bits": 0,
  "difficulty": 0,
  "sizeBytes": 0,
  "weight": 0,
  "txCount": 0,
  "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
}

Error responses

HTTP 404

block not found

{
  "error": "block not found"
}

HTTP 500

failed to load latest block

{
  "error": "failed to load latest block"
}

GET

/api/v1/blocks/{id}

Block detail

Loads one block by height or block hash.

BlockSummary

Parameters

path

string

required

Block height or block hash.

JSON

BlockSummary

Single block summary payload.

Top-level fields

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "height": 0,
  "hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "version": 0,
  "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
  "time": "2026-03-19T20:00:00Z",
  "medianTime": "2026-03-19T20:00:00Z",
  "nonce": 0,
  "bits": 0,
  "difficulty": 0,
  "sizeBytes": 0,
  "weight": 0,
  "txCount": 0,
  "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
}

Error responses

HTTP 400

missing block identifier

{
  "error": "missing block identifier"
}

HTTP 404

block not found

{
  "error": "block not found"
}

HTTP 500

failed to load block

{
  "error": "failed to load block"
}

GET

/api/v1/blocks/{id}/transactions

Block transactions

Returns transaction summaries for a specific block.

TransactionSummaryListResponse

Parameters

path

string

required

Block height or block hash.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

TransactionSummaryListResponse

Paginated transaction summaries scoped to one block.

Top-level fields

items[]: TransactionSummarypagination.limitpagination.offset

Item details

txidblockHeightblockPositionversionlockTimesizeBytesweighttotalInputSatstotalOutputSatsfeeSatsisCoinbase

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "blockHeight": 0,
      "blockPosition": 0,
      "version": 0,
      "lockTime": "2026-03-19T20:00:00Z",
      "sizeBytes": 0,
      "weight": 0,
      "totalInputSats": 0,
      "totalOutputSats": 0,
      "feeSats": 0,
      "isCoinbase": true
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing block identifier, invalid limit, or invalid offset

{
  "error": "missing block identifier, invalid limit, or invalid offset"
}

HTTP 404

block not found

{
  "error": "block not found"
}

HTTP 500

failed to load block transactions

{
  "error": "failed to load block transactions"
}

Transactions

3 endpoints

Transactions

Transaction detail, confirmation status, and raw-hex access.

GET

/api/v1/transactions/{txid}

Transaction detail

Returns a full transaction model including inputs and outputs.

TransactionResponse

Parameters

txid

path

string

required

Transaction identifier.

JSON

TransactionResponse

Full transaction payload.

Top-level fields

txidblockHeightblockPositionversionlockTimesizeBytesweighttotalInputSatstotalOutputSatsfeeSatsisCoinbaseinputs[]outputs[]

Item details

inputs[].inputIndexinputs[].prevTxidinputs[].prevOutputIndexinputs[].scriptSiginputs[].sequenceinputs[].coinbaseDatainputs[].valueSatsinputs[].addressoutputs[].outputIndexoutputs[].valueSatsoutputs[].scriptPubKeyoutputs[].scriptTypeoutputs[].requiredSignaturesoutputs[].addressoutputs[].spentByTxidoutputs[].spentByInputIndexoutputs[].spent

Success example

{
  "txid": "1111111111111111111111111111111111111111111111111111111111111111",
  "blockHeight": 0,
  "blockPosition": 0,
  "version": 0,
  "lockTime": "2026-03-19T20:00:00Z",
  "sizeBytes": 0,
  "weight": 0,
  "totalInputSats": 0,
  "totalOutputSats": 0,
  "feeSats": 0,
  "isCoinbase": true,
  "inputs": [
    {
      "inputIndex": 0,
      "prevTxid": "1111111111111111111111111111111111111111111111111111111111111111",
      "prevOutputIndex": 0,
      "scriptSig": 0,
      "sequence": 0,
      "coinbaseData": 0,
      "valueSats": 0,
      "address": "BdtExampleAddress123"
    }
  ],
  "outputs": [
    {
      "outputIndex": 0,
      "valueSats": 0,
      "scriptPubKey": 0,
      "scriptType": 0,
      "requiredSignatures": 0,
      "address": "BdtExampleAddress123",
      "spentByTxid": "1111111111111111111111111111111111111111111111111111111111111111",
      "spentByInputIndex": 0,
      "spent": 0
    }
  ]
}

Error responses

HTTP 400

missing transaction id

{
  "error": "missing transaction id"
}

HTTP 404

transaction not found

{
  "error": "transaction not found"
}

HTTP 500

failed to load transaction

{
  "error": "failed to load transaction"
}

GET

/api/v1/transactions/{txid}/status

Transaction status

Returns confirmation metadata without the full transaction body.

TransactionStatus

Parameters

txid

path

string

required

Transaction identifier.

JSON

TransactionStatus

Confirmation status payload.

Top-level fields

txidconfirmedblockHeightblockHashblockPosition

Success example

{
  "txid": "1111111111111111111111111111111111111111111111111111111111111111",
  "confirmed": 0,
  "blockHeight": 0,
  "blockHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "blockPosition": 0
}

Error responses

HTTP 400

missing transaction id

{
  "error": "missing transaction id"
}

HTTP 404

transaction not found

{
  "error": "transaction not found"
}

HTTP 500

failed to load transaction status

{
  "error": "failed to load transaction status"
}

GET

/api/v1/transactions/{txid}/raw

Raw transaction hex

Returns the serialized raw transaction hex string.

TransactionRaw

Parameters

txid

path

string

required

Transaction identifier.

JSON

TransactionRaw

Raw transaction payload.

Top-level fields

txidhex

Success example

{
  "txid": "1111111111111111111111111111111111111111111111111111111111111111",
  "hex": 0
}

Error responses

HTTP 400

missing transaction id

{
  "error": "missing transaction id"
}

HTTP 404

transaction not found

{
  "error": "transaction not found"
}

HTTP 500

failed to load raw transaction

{
  "error": "failed to load raw transaction"
}

Addresses

4 endpoints

Addresses

Address detail plus related transaction, UTXO, and balance-history routes.

GET

/api/v1/addresses/{address}

Address detail

Returns aggregate address statistics and first/last seen information.

AddressResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

JSON

AddressResponse

Single address summary.

Top-level fields

addressfirstSeenHeightfirstSeenTxidlastSeenHeightlastSeenTxidoutputCountinputCountfundedSatsspentSatsbalanceSatstxCountreceivedTxCountsentTxCount

Success example

{
  "address": "BdtExampleAddress123",
  "firstSeenHeight": 0,
  "firstSeenTxid": "1111111111111111111111111111111111111111111111111111111111111111",
  "lastSeenHeight": 0,
  "lastSeenTxid": "1111111111111111111111111111111111111111111111111111111111111111",
  "outputCount": 0,
  "inputCount": 0,
  "fundedSats": 0,
  "spentSats": 0,
  "balanceSats": 0,
  "txCount": 0,
  "receivedTxCount": 0,
  "sentTxCount": 0
}

Error responses

HTTP 400

missing address

{
  "error": "missing address"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address

{
  "error": "failed to load address"
}

Notes

Frontend normalization accepts fundedSats and spentSats as either integer JSON values or strings before converting to bigint.

GET

/api/v1/addresses/{address}/transactions

Address transactions

Returns paginated full transaction details touching the address.

TransactionListResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

TransactionListResponse

Paginated full transaction payloads.

Top-level fields

items[]: TransactionResponsepagination.limitpagination.offset

Item details

txidblockHeightblockPositionversionlockTimesizeBytesweighttotalInputSatstotalOutputSatsfeeSatsisCoinbaseinputs[]outputs[]

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "blockHeight": 0,
      "blockPosition": 0,
      "version": 0,
      "lockTime": "2026-03-19T20:00:00Z",
      "sizeBytes": 0,
      "weight": 0,
      "totalInputSats": 0,
      "totalOutputSats": 0,
      "feeSats": 0,
      "isCoinbase": true,
      "inputs": [
        {}
      ],
      "outputs": [
        {}
      ]
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing address, invalid limit, or invalid offset

{
  "error": "missing address, invalid limit, or invalid offset"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address transactions

{
  "error": "failed to load address transactions"
}

GET

/api/v1/addresses/{address}/utxos

Address UTXOs

Returns spendable and historical UTXO records for the address.

AddressUtxoListResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

AddressUtxoListResponse

Paginated UTXO list.

Top-level fields

items[]: AddressUtxopagination.limitpagination.offset

Item details

txidoutputIndexblockHeightvalueSatsscriptPubKeyscriptTyperequiredSignatures

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "outputIndex": 0,
      "blockHeight": 0,
      "valueSats": 0,
      "scriptPubKey": 0,
      "scriptType": 0,
      "requiredSignatures": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing address, invalid limit, or invalid offset

{
  "error": "missing address, invalid limit, or invalid offset"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address utxos

{
  "error": "failed to load address utxos"
}

GET

/api/v1/addresses/{address}/balance-history

Address balance history

Returns historical balance deltas over indexed blocks.

AddressBalanceHistoryResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

AddressBalanceHistoryResponse

Paginated balance history points.

Top-level fields

items[]: AddressBalanceHistoryPointpagination.limitpagination.offset

Item details

blockHeightblockTimedeltaSatsbalanceSats

Success example

{
  "items": [
    {
      "blockHeight": 0,
      "blockTime": "2026-03-19T20:00:00Z",
      "deltaSats": 0,
      "balanceSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing address, invalid limit, or invalid offset

{
  "error": "missing address, invalid limit, or invalid offset"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address balance history

{
  "error": "failed to load address balance history"
}

Holders and labels

8 endpoints

Holders and labels

Holder leaderboards, distribution views, snapshots, and locked-allocation labeling.

GET

/api/v1/holders/top

Top holders

Returns paginated positive-balance holder rows.

HolderListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

HolderListResponse

Paginated holder list.

Top-level fields

items[]: Holderpagination.limitpagination.offset

Item details

addressbalanceSatsfundedSatsspentSatstxCountreceivedTxCountsentTxCountfirstSeenHeightlastSeenHeight

Success example

{
  "items": [
    {
      "address": "BdtExampleAddress123",
      "balanceSats": 0,
      "fundedSats": 0,
      "spentSats": 0,
      "txCount": 0,
      "receivedTxCount": 0,
      "sentTxCount": 0,
      "firstSeenHeight": 0,
      "lastSeenHeight": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load holders

{
  "error": "failed to load holders"
}

GET

/api/v1/holders/leaderboard

Combined holder leaderboard

Returns locked allocation rows plus a paginated regular-holder page.

HolderLeaderboardResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

HolderLeaderboardResponse

Composite leaderboard payload.

Top-level fields

lockedAllocations.items[]: LockedAllocationItemlockedAllocations.summary: LockedAllocationSummaryholders.items[]: Holderholders.pagination.limitholders.pagination.offset

Item details

labeladdressbalanceSatsexpectedBalanceSatssharePercentaddressbalanceSatsfundedSatsspentSatstxCountreceivedTxCountsentTxCountfirstSeenHeightlastSeenHeight

Success example

{
  "lockedAllocations": {
    "items": [
      {
        "label": "example",
        "address": "BdtExampleAddress123",
        "balanceSats": 0,
        "expectedBalanceSats": 0,
        "sharePercent": 0,
        "fundedSats": 0,
        "spentSats": 0,
        "txCount": 0,
        "receivedTxCount": 0,
        "sentTxCount": 0,
        "firstSeenHeight": 0,
        "lastSeenHeight": 0
      }
    ],
    "summary": 0
  },
  "holders": {
    "items": [
      {
        "label": "example",
        "address": "BdtExampleAddress123",
        "balanceSats": 0,
        "expectedBalanceSats": 0,
        "sharePercent": 0,
        "fundedSats": 0,
        "spentSats": 0,
        "txCount": 0,
        "receivedTxCount": 0,
        "sentTxCount": 0,
        "firstSeenHeight": 0,
        "lastSeenHeight": 0
      }
    ],
    "pagination": {
      "limit": 0,
      "offset": 0
    }
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load holder leaderboard

{
  "error": "failed to load holder leaderboard"
}

GET

/api/v1/holders/buckets

Holder buckets

Returns holder concentration buckets with tracked balance totals.

HolderDistributionResponse

JSON

HolderDistributionResponse

Bucket distribution payload.

Top-level fields

buckets[]totalHolderCounttotalTrackedBalanceSatsindexedTipHeight

Item details

buckets[].minBalanceSatsbuckets[].maxBalanceSatsbuckets[].openEndedbuckets[].addressCountbuckets[].totalBalanceSats

Success example

{
  "buckets": [
    {
      "minBalanceSats": 0,
      "maxBalanceSats": 0,
      "openEnded": true,
      "addressCount": "BdtExampleAddress123",
      "totalBalanceSats": 0
    }
  ],
  "totalHolderCount": 0,
  "totalTrackedBalanceSats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load holder buckets

{
  "error": "failed to load holder buckets"
}

GET

/api/v1/holders/distribution

Holder distribution

Returns the same bucketed holder-distribution contract used across analytics views.

HolderDistributionResponse

JSON

HolderDistributionResponse

Bucket distribution payload.

Top-level fields

buckets[]totalHolderCounttotalTrackedBalanceSatsindexedTipHeight

Item details

buckets[].minBalanceSatsbuckets[].maxBalanceSatsbuckets[].openEndedbuckets[].addressCountbuckets[].totalBalanceSats

Success example

{
  "buckets": [
    {
      "minBalanceSats": 0,
      "maxBalanceSats": 0,
      "openEnded": true,
      "addressCount": "BdtExampleAddress123",
      "totalBalanceSats": 0
    }
  ],
  "totalHolderCount": 0,
  "totalTrackedBalanceSats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load holder distribution

{
  "error": "failed to load holder distribution"
}

GET

/api/v1/holders/snapshots

Holder snapshots

Returns ranked point-in-time holder snapshots.

HolderSnapshotsResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

HolderSnapshotsResponse

Snapshot payload with pagination.

Top-level fields

items[]: HolderSnapshotItemsnapshotTimetotalHolderCountindexedTipHeightpagination.limitpagination.offset

Item details

addressrankbalanceSatsbucket

Success example

{
  "items": [
    {
      "address": "BdtExampleAddress123",
      "rank": 0,
      "balanceSats": 0,
      "bucket": 0
    }
  ],
  "snapshotTime": "2026-03-19T20:00:00Z",
  "totalHolderCount": 0,
  "indexedTipHeight": 0,
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load holder snapshots

{
  "error": "failed to load holder snapshots"
}

GET

/api/v1/labels/locked-allocation

Locked allocation list

Returns paginated labeled locked-allocation addresses.

LockedAllocationListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

LockedAllocationListResponse

Paginated locked-allocation list.

Top-level fields

items[]: LockedAllocationItempagination.limitpagination.offset

Item details

labeladdressbalanceSatsexpectedBalanceSatssharePercent

Success example

{
  "items": [
    {
      "label": "example",
      "address": "BdtExampleAddress123",
      "balanceSats": 0,
      "expectedBalanceSats": 0,
      "sharePercent": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load locked allocation

{
  "error": "failed to load locked allocation"
}

GET

/api/v1/labels/locked-allocation/summary

Locked allocation summary

Returns aggregate totals for tracked locked-allocation addresses.

LockedAllocationSummary

JSON

LockedAllocationSummary

Aggregate locked-allocation totals.

Top-level fields

totalBalanceSatstotalExpectedBalanceSatslabeledAddressCountindexedTipHeight

Success example

{
  "totalBalanceSats": 0,
  "totalExpectedBalanceSats": 0,
  "labeledAddressCount": "BdtExampleAddress123",
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load locked allocation summary

{
  "error": "failed to load locked allocation summary"
}

GET

/api/v1/labels/locked-allocation/series

Locked allocation series

Returns time-series changes for locked-allocation balances.

LockedAllocationSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

LockedAllocationSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: LockedAllocationSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daynetChangeSatstotalBalanceSats

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "netChangeSats": 0,
      "totalBalanceSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load locked allocation series

{
  "error": "failed to load locked allocation series"
}

Live and mempool

11 endpoints

Live and mempool

Realtime explorer snapshots, stream transport, mempool state, and mempool analytics.

GET

/api/v1/live/summary

Live summary

Returns a compact live snapshot used by streaming and homepage status surfaces.

LiveSummary

JSON

LiveSummary

Current live explorer summary.

Top-level fields

blockCounttransactionCountaddressCounttotalTrackedBalanceSatslatestBlockHeightlatestBlockHashlatestBlockTime

Success example

{
  "blockCount": 0,
  "transactionCount": 0,
  "addressCount": "BdtExampleAddress123",
  "totalTrackedBalanceSats": 0,
  "latestBlockHeight": 0,
  "latestBlockHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "latestBlockTime": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load live summary

{
  "error": "failed to load live summary"
}

GET

/api/v1/live/blocks

Live blocks history

Returns the latest blocks with standard pagination.

BlockListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

BlockListResponse

Paginated recent blocks list.

Top-level fields

items[]: BlockSummarypagination.limitpagination.offset

Item details

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "items": [
    {
      "height": 0,
      "hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "version": 0,
      "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
      "time": "2026-03-19T20:00:00Z",
      "medianTime": "2026-03-19T20:00:00Z",
      "nonce": 0,
      "bits": 0,
      "difficulty": 0,
      "sizeBytes": 0,
      "weight": 0,
      "txCount": 0,
      "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load live blocks

{
  "error": "failed to load live blocks"
}

GET

/api/v1/live/events

Live events history

Returns paginated block-event history using the shared series filter contract.

LiveEventListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

LiveEventListResponse

Paginated event history payload.

Top-level fields

items[]: LiveEventpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

typeblockHeightblockHashblockTimetxCount

Success example

{
  "items": [
    {
      "type": 0,
      "blockHeight": 0,
      "blockHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "blockTime": "2026-03-19T20:00:00Z",
      "txCount": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load live events

{
  "error": "failed to load live events"
}

GET

/api/v1/live/events/stream

Live events stream

Server-sent event stream that pushes summary, mempool, and latest-block snapshots.

LiveEventStream

SSE

LiveEventStream

text/event-stream transport with named JSON payload events.

Top-level fields

Content-Type: text/event-streamCache-Control: no-cacheConnection: keep-aliveretry: 5000 emitted on connect

Emitted events

summary

LiveSummary

mempool_summary

MempoolSummary

blocks

BlockListResponse(limit=5, offset=0)

Success example

retry: 5000

event: summary
data: {"indexedTipHeight": 917135}

event: blocks
data: [{"height": 917135}]

Error responses

HTTP 500

streaming not supported or stream initialization failed

{
  "error": "streaming not supported or stream initialization failed"
}

GET

/api/v1/mempool/summary

Mempool summary

Returns aggregate mempool counts, bytes, and fee totals.

MempoolSummary

JSON

MempoolSummary

Current mempool summary.

Top-level fields

transactionCountbytesusageBytestotalFeeSatsloaded

Success example

{
  "transactionCount": 0,
  "bytes": 0,
  "usageBytes": 0,
  "totalFeeSats": 0,
  "loaded": 0
}

Error responses

HTTP 500

failed to load mempool summary

{
  "error": "failed to load mempool summary"
}

GET

/api/v1/mempool/transactions

Mempool transactions

Returns paginated mempool transactions ordered for explorer listing.

MempoolTransactionListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MempoolTransactionListResponse

Paginated mempool transaction list.

Top-level fields

items[]: MempoolTransactionpagination.limitpagination.offset

Item details

txidvirtualSizeBytesweightfeeSatsmodifiedFeeSatsfeeRateSatPerVByte (jus/vB)timeheightancestorCountdescendantCount

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "virtualSizeBytes": 0,
      "weight": 0,
      "feeSats": 0,
      "modifiedFeeSats": 0,
      "feeRateSatPerVByte": 0,
      "time": "2026-03-19T20:00:00Z",
      "height": 0,
      "ancestorCount": 0,
      "descendantCount": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load mempool transactions

{
  "error": "failed to load mempool transactions"
}

GET

/api/v1/mempool/recent

Recent mempool transactions

Returns the latest mempool arrivals with the same DTO as the full mempool list.

MempoolTransactionListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MempoolTransactionListResponse

Paginated recent mempool transaction list.

Top-level fields

items[]: MempoolTransactionpagination.limitpagination.offset

Item details

txidvirtualSizeBytesfeeSatsfeeRateSatPerVByte (jus/vB)time

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "virtualSizeBytes": 0,
      "feeSats": 0,
      "feeRateSatPerVByte": 0,
      "time": "2026-03-19T20:00:00Z"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load recent mempool transactions

{
  "error": "failed to load recent mempool transactions"
}

GET

/api/v1/mempool/fees

Fee estimates

Returns next-block and short-horizon fee guidance.

MempoolFees

JSON

MempoolFees

Fee estimate summary.

Top-level fields

nextBlock.smartnextBlock.minnextBlock.maxnextBlock.median30min60min1day

Success example

{
  "nextBlock": {
    "smart": 0,
    "min": 0,
    "max": 0,
    "median": 0
  },
  "30min": 0,
  "60min": 0,
  "1day": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load mempool fees

{
  "error": "failed to load mempool fees"
}

GET

/api/v1/mempool/buckets

Fee-rate buckets

Returns mempool composition grouped by fee-rate band.

MempoolFeeRateBucketResponse

JSON

MempoolFeeRateBucketResponse

Bucketed fee-rate analytics.

Top-level fields

items[]: MempoolFeeRateBucket

Item details

minFeeRateSatPerVByte (jus/vB)maxFeeRateSatPerVByte (jus/vB)openEndedtransactionCounttotalVirtualSizeBytestotalFeeSats

Success example

{
  "items": [
    {
      "minFeeRateSatPerVByte": 0,
      "maxFeeRateSatPerVByte": 0,
      "openEnded": true,
      "transactionCount": 0,
      "totalVirtualSizeBytes": 0,
      "totalFeeSats": 0
    }
  ]
}

Error responses

HTTP 500

failed to load mempool fee rate buckets

{
  "error": "failed to load mempool fee rate buckets"
}

GET

/api/v1/mempool/age-distribution

Mempool age distribution

Returns mempool composition grouped by transaction age.

MempoolAgeDistributionResponse

JSON

MempoolAgeDistributionResponse

Bucketed age analytics.

Top-level fields

items[]: MempoolAgeBucket

Item details

minAgeSecondsmaxAgeSecondsopenEndedtransactionCounttotalVirtualSizeBytes

Success example

{
  "items": [
    {
      "minAgeSeconds": 0,
      "maxAgeSeconds": 0,
      "openEnded": true,
      "transactionCount": 0,
      "totalVirtualSizeBytes": 0
    }
  ]
}

Error responses

HTTP 500

failed to load mempool age distribution

{
  "error": "failed to load mempool age distribution"
}

GET

/api/v1/mempool/size-distribution

Mempool size distribution

Returns mempool composition grouped by virtual-size band.

MempoolSizeDistributionResponse

JSON

MempoolSizeDistributionResponse

Bucketed size analytics.

Top-level fields

items[]: MempoolSizeBucket

Item details

minVirtualSizeBytesmaxVirtualSizeBytesopenEndedtransactionCounttotalVirtualSizeBytes

Success example

{
  "items": [
    {
      "minVirtualSizeBytes": 0,
      "maxVirtualSizeBytes": 0,
      "openEnded": true,
      "transactionCount": 0,
      "totalVirtualSizeBytes": 0
    }
  ]
}

Error responses

HTTP 500

failed to load mempool size distribution

{
  "error": "failed to load mempool size distribution"
}

Miners and whale analytics

7 endpoints

Miners and whale analytics

Miner production datasets and whale-transfer analytics endpoints.

GET

/api/v1/miners/summary

Miner summary

Returns miner ranking and network share totals.

MinerSummaryResponse

JSON

MinerSummaryResponse

Miner summary payload.

Top-level fields

items[]: MinerSummaryItemtotalMinerCounttotalMinedBlockCountindexedTipHeight

Item details

minerNameblockCounttotalRewardSatssharePercentlatestBlockHeightlatestBlockTime

Success example

{
  "items": [
    {
      "minerName": "example",
      "blockCount": 0,
      "totalRewardSats": 0,
      "sharePercent": 0,
      "latestBlockHeight": 0,
      "latestBlockTime": "2026-03-19T20:00:00Z"
    }
  ],
  "totalMinerCount": 0,
  "totalMinedBlockCount": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load miners summary

{
  "error": "failed to load miners summary"
}

GET

/api/v1/miners/compare

Compare miners

Returns paginated miner detail rows and optionally filters by repeated name query params.

MinerCompareResponse

Parameters

name

query

string[]

Repeatable miner name filter.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MinerCompareResponse

Paginated miner comparison list.

Top-level fields

items[]: MinerDetailBasepagination.limitpagination.offset

Item details

minerNameblockCounttotalRewardSatssharePercentlatestBlockHeightlatestBlockTimeaverageRewardSatsindexedTipHeight

Success example

{
  "items": [
    {
      "minerName": "example",
      "blockCount": 0,
      "totalRewardSats": 0,
      "sharePercent": 0,
      "latestBlockHeight": 0,
      "latestBlockTime": "2026-03-19T20:00:00Z",
      "averageRewardSats": 0,
      "indexedTipHeight": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 404

miner not found

{
  "error": "miner not found"
}

HTTP 500

failed to compare miners

{
  "error": "failed to compare miners"
}

GET

/api/v1/miners/series

Miner series

Returns paginated daily miner production rows.

MinerSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MinerSeriesResponse

Paginated miner series payload.

Top-level fields

items[]: MinerSeriesPointpagination.limitpagination.offset

Item details

dayminerNameblockCounttotalRewardSats

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "minerName": "example",
      "blockCount": 0,
      "totalRewardSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load miner series

{
  "error": "failed to load miner series"
}

GET

/api/v1/miners/{name}

Miner detail

Returns a miner detail row and optionally nests dailySeries when include=dailySeries is present.

MinerDetailResponse

Parameters

name

path

string

required

Miner name.

include

query

dailySeries

Optional nested daily-series include.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MinerDetailResponse

Miner detail payload with optional nested dailySeries list.

Top-level fields

minerNameblockCounttotalRewardSatssharePercentlatestBlockHeightlatestBlockTimeaverageRewardSatsindexedTipHeightdailySeries?: { items[], pagination }

Item details

dailySeries.items[].daydailySeries.items[].blockCountdailySeries.items[].totalRewardSats

Success example

{
  "minerName": "example",
  "blockCount": 0,
  "totalRewardSats": 0,
  "sharePercent": 0,
  "latestBlockHeight": 0,
  "latestBlockTime": "2026-03-19T20:00:00Z",
  "averageRewardSats": 0,
  "indexedTipHeight": 0,
  "dailySeries": {
    "items": [
      {
        "day": "2026-03-19T20:00:00Z",
        "blockCount": 0,
        "totalRewardSats": 0
      }
    ],
    "pagination": 0
  }
}

Error responses

HTTP 400

invalid include, limit, or offset

{
  "error": "invalid include, limit, or offset"
}

HTTP 404

miner not found

{
  "error": "miner not found"
}

HTTP 500

failed to load miner detail

{
  "error": "failed to load miner detail"
}

GET

/api/v1/analytics/whales/events

Whale events

Returns paginated whale transfer events above the configured backend threshold.

WhaleEventListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

WhaleEventListResponse

Paginated whale event list.

Top-level fields

items[]: WhaleEventpagination.limitpagination.offset

Item details

txidoutputIndexblockHeightblockTimeaddressvalueSats

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "outputIndex": 0,
      "blockHeight": 0,
      "blockTime": "2026-03-19T20:00:00Z",
      "address": "BdtExampleAddress123",
      "valueSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load whale events

{
  "error": "failed to load whale events"
}

GET

/api/v1/analytics/whales/summary

Whale summary

Returns summary metrics and optionally latestEvents when include=latestEvents is requested.

WhaleSummaryResponse

Parameters

include

query

latestEvents

Optional nested latest whale events include.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

WhaleSummaryResponse

Whale summary payload with optional nested latestEvents list.

Top-level fields

eventCounttotalValueSatsuniqueAddressCountindexedTipHeightthresholdSatslatestEvents?: { items[], pagination }

Item details

latestEvents.items[].txidlatestEvents.items[].blockHeightlatestEvents.items[].addresslatestEvents.items[].valueSats

Success example

{
  "eventCount": 0,
  "totalValueSats": 0,
  "uniqueAddressCount": "BdtExampleAddress123",
  "indexedTipHeight": 0,
  "thresholdSats": 0,
  "latestEvents": {
    "items": [
      {
        "txid": "1111111111111111111111111111111111111111111111111111111111111111",
        "blockHeight": 0,
        "address": "BdtExampleAddress123",
        "valueSats": 0
      }
    ],
    "pagination": 0
  }
}

Error responses

HTTP 400

invalid include, limit, or offset

{
  "error": "invalid include, limit, or offset"
}

HTTP 500

failed to load whale summary

{
  "error": "failed to load whale summary"
}

GET

/api/v1/analytics/whales/series

Whale series

Returns whale-event totals over time using shared series filters.

WhaleSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

WhaleSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: WhaleSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

dayeventCounttotalValueSats

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "eventCount": 0,
      "totalValueSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load whale series

{
  "error": "failed to load whale series"
}

Market and supply

7 endpoints

Market and supply

Supply state, distribution buckets, and market summary pricing signals.

GET

/api/v1/market/summary

Market summary

Returns current exchange-rate and market-cap style metrics.

MarketSummary

JSON

MarketSummary

Market snapshot payload.

Top-level fields

exchangeRatemarketCapgoldRatevolume24hcurrencyupdatedAt

Success example

{
  "exchangeRate": 0,
  "marketCap": 0,
  "goldRate": 0,
  "volume24h": 0,
  "currency": "USD",
  "updatedAt": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load market summary

{
  "error": "failed to load market summary"
}

GET

/api/v1/supply

Supply summary

Returns issued, mined, total, max, circulating, unmined, and locked supply totals.

SupplySummary

JSON

SupplySummary

Supply state payload.

Top-level fields

issuedSupplySatsunspentSupplySatsunspentOutputCountindexedTipHeightmaxSupplySatstotalSupplySatstotalMinedSatscirculatingSupplySatsunminedSupplySatslockedAllocationSats

Success example

{
  "issuedSupplySats": 0,
  "unspentSupplySats": 0,
  "unspentOutputCount": 0,
  "indexedTipHeight": 0,
  "maxSupplySats": 0,
  "totalSupplySats": 0,
  "totalMinedSats": 0,
  "circulatingSupplySats": 0,
  "unminedSupplySats": 0,
  "lockedAllocationSats": 0
}

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

GET

/api/v1/supply/distribution

Supply distribution

Returns supply concentration buckets across tracked balances.

SupplyDistribution

JSON

SupplyDistribution

Bucketed supply distribution payload.

Top-level fields

buckets[]totalTrackedSupplySatsindexedTipHeight

Item details

buckets[].minBalanceSatsbuckets[].maxBalanceSatsbuckets[].openEndedbuckets[].addressCountbuckets[].totalBalanceSats

Success example

{
  "buckets": [
    {
      "minBalanceSats": 0,
      "maxBalanceSats": 0,
      "openEnded": true,
      "addressCount": "BdtExampleAddress123",
      "totalBalanceSats": 0
    }
  ],
  "totalTrackedSupplySats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load supply distribution

{
  "error": "failed to load supply distribution"
}

GET

/api/unmined-coins

Unmined coins alias

Returns the remaining mineable supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> unminedSupplySats.
Response body is plain text in BDTC, not a JSON object and not atomic units.

GET

/api/circulating-supply

Circulating supply alias

Returns circulating supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> circulatingSupplySats.
Response body is plain text in BDTC, not a JSON object and not atomic units.

GET

/api/max-supply

Max supply alias

Returns the protocol max supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> maxSupplySats.
Response body is plain text in BDTC, not a JSON object and not atomic units.

GET

/api/total-supply

Total supply alias

Returns total supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> totalSupplySats.
Under the current supply contract this matches max supply. Response body is plain text in BDTC, not a JSON object and not atomic units.

Network stats

9 endpoints

Network stats

Overview totals plus transaction, address, mining, fee, and block series analytics.

GET

/api/v1/stats/overview

Overview stats

Returns top-level indexed chain totals.

StatsOverview

JSON

StatsOverview

Overview metric payload.

Top-level fields

blockCounttransactionCountaddressCountindexedTipHeight

Success example

{
  "blockCount": 0,
  "transactionCount": 0,
  "addressCount": "BdtExampleAddress123",
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load stats overview

{
  "error": "failed to load stats overview"
}

GET

/api/v1/stats/transactions

Transaction stats

Returns aggregate transaction metrics.

StatsTransactions

JSON

StatsTransactions

Transaction metrics payload.

Top-level fields

transactionCountcoinbaseTransactionCountnonCoinbaseTransactionCounttotalFeesSatsaverageFeeSatsaverageSizeBytesaverageWeightindexedTipHeight

Success example

{
  "transactionCount": 0,
  "coinbaseTransactionCount": 0,
  "nonCoinbaseTransactionCount": 0,
  "totalFeesSats": 0,
  "averageFeeSats": 0,
  "averageSizeBytes": 0,
  "averageWeight": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load transaction stats

{
  "error": "failed to load transaction stats"
}

GET

/api/v1/stats/transactions/series

Transaction series

Returns transaction metrics over time.

StatsTransactionsSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsTransactionsSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsTransactionsSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daytransactionCountcoinbaseTransactionCountnonCoinbaseTransactionCounttotalFeesSatsaverageFeeSatsaverageSizeBytesaverageWeight

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "transactionCount": 0,
      "coinbaseTransactionCount": 0,
      "nonCoinbaseTransactionCount": 0,
      "totalFeesSats": 0,
      "averageFeeSats": 0,
      "averageSizeBytes": 0,
      "averageWeight": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load transaction stats series

{
  "error": "failed to load transaction stats series"
}

GET

/api/v1/stats/addresses

Address stats

Returns indexed address and balance totals.

StatsAddresses

JSON

StatsAddresses

Address metrics payload.

Top-level fields

addressCountfundedAddressCountzeroBalanceAddressCounttotalTrackedBalanceSatstotalFundedSatstotalSpentSatsindexedTipHeight

Success example

{
  "addressCount": "BdtExampleAddress123",
  "fundedAddressCount": "BdtExampleAddress123",
  "zeroBalanceAddressCount": "BdtExampleAddress123",
  "totalTrackedBalanceSats": 0,
  "totalFundedSats": 0,
  "totalSpentSats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load address stats

{
  "error": "failed to load address stats"
}

GET

/api/v1/stats/addresses/series

Address series

Returns address-growth and address-activity metrics over time.

StatsAddressesSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsAddressesSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsAddressesSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daynewAddressCountcumulativeAddressCountactiveAddressCountreceivingAddressCountsendingAddressCount

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "newAddressCount": "BdtExampleAddress123",
      "cumulativeAddressCount": "BdtExampleAddress123",
      "activeAddressCount": "BdtExampleAddress123",
      "receivingAddressCount": "BdtExampleAddress123",
      "sendingAddressCount": "BdtExampleAddress123"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load address stats series

{
  "error": "failed to load address stats series"
}

GET

/api/v1/stats/mining

Mining stats

Returns aggregate block-production metrics.

StatsMining

JSON

StatsMining

Mining metric payload.

Top-level fields

blockCountaverageBlockSizeBytesaverageBlockWeightaverageTransactionsPerBlocklatestBlockHeightlatestBlockTime

Success example

{
  "blockCount": 0,
  "averageBlockSizeBytes": 0,
  "averageBlockWeight": 0,
  "averageTransactionsPerBlock": 0,
  "latestBlockHeight": 0,
  "latestBlockTime": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load mining stats

{
  "error": "failed to load mining stats"
}

GET

/api/v1/stats/mining/series

Mining series

Returns mining metrics over time.

StatsMiningSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsMiningSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsMiningSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

dayblockCountaverageBlockSizeBytesaverageBlockWeightaverageTransactionsPerBlock

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "blockCount": 0,
      "averageBlockSizeBytes": 0,
      "averageBlockWeight": 0,
      "averageTransactionsPerBlock": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load mining stats series

{
  "error": "failed to load mining stats series"
}

GET

/api/v1/stats/fees/series

Fee series

Returns fee totals and fee-rate averages over time.

StatsFeesSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsFeesSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsFeesSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daytotalFeesSatsaverageFeeSatsaverageFeeRateSatPerVByte (jus/vB)

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "totalFeesSats": 0,
      "averageFeeSats": 0,
      "averageFeeRateSatPerVByte": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load fee stats series

{
  "error": "failed to load fee stats series"
}

GET

/api/v1/stats/blocks/series

Block series

Returns block-production and interval metrics over time.

StatsBlocksSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsBlocksSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsBlocksSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

dayblockCountaverageBlockSizeBytesaverageBlockWeightaverageTransactionsPerBlockaverageDifficultyaverageBlockIntervalSeconds

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "blockCount": 0,
      "averageBlockSizeBytes": 0,
      "averageBlockWeight": 0,
      "averageTransactionsPerBlock": 0,
      "averageDifficulty": 0,
      "averageBlockIntervalSeconds": "example"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load block stats series

{
  "error": "failed to load block stats series"
}

2 endpoints

Search

Exact-match search resolution and live suggestion APIs used by the explorer search experience.

GET

/api/v1/search

Resolve search query

Attempts to resolve a query into one exact block, transaction, or address result.

SearchResponse

Parameters

query

string

required

Search query string.

JSON

SearchResponse

Single exact-match search result.

Top-level fields

querytypeidpathfound

Success example

{
  "query": 0,
  "type": 0,
  "id": 0,
  "path": 0,
  "found": 0
}

Error responses

HTTP 400

missing search query

{
  "error": "missing search query"
}

HTTP 404

search result not found

{
  "error": "search result not found"
}

HTTP 500

failed to resolve search query

{
  "error": "failed to resolve search query"
}

GET

/api/v1/search/suggest

Search suggestions

Returns a lightweight suggestion list for partial search input.

SearchSuggestionListResponse

Parameters

query

string

required

Search query string.

limit

query

integer

Maximum suggestion count. Defaults to 5.

JSON

SearchSuggestionListResponse

Suggestion list payload.

Top-level fields

items[]: SearchSuggestion

Item details

typeidpathlabel

Success example

{
  "items": [
    {
      "type": 0,
      "id": 0,
      "path": 0,
      "label": "example"
    }
  ]
}

Error responses

HTTP 400

missing search query

{
  "error": "missing search query"
}

HTTP 400

invalid limit

{
  "error": "invalid limit"
}

HTTP 500

failed to load search suggestions

{
  "error": "failed to load search suggestions"
}

API Docs

Backend explorer API reference

Loading grouped routes, DTO contracts, response rules, and endpoint details for the explorer backend.

API Docs

Backend explorer API reference

Route groups

Grouped by service responsibility so related DTOs stay together.

Total endpoints

Includes health, explorer JSON routes, same-origin text aliases, analytics, and streaming transport.

JSON responses

Routes returning standard application/json envelopes or singleton DTOs.

Text responses

Legacy-compatible same-origin aliases returning plain-text coin values.

Streaming routes

Current realtime transport exposed as server-sent events.

Shared contracts and response rules

These rules appear across multiple handlers and are useful before you inspect the individual route cards.

Shared error response

Most backend failures return the same JSON error envelope.

Transport: application/json
Payload: single top-level error message string
Used for 400 validation failures, 404 misses, and 500 service failures

{
  "error": "failed to load blocks"
}

Shared list response shape

List-style endpoints reuse the frontend paging contract validated by Zod.

items: array payload
pagination.limit / pagination.offset when paging applies
filters.from / filters.to / filters.range / filters.interval on series-style endpoints
meta.lastUpdated may appear when a route supplies extra metadata

{
  "items": [],
  "pagination": { "limit": 20, "offset": 0 },
  "filters": { "range": "30d", "interval": "day" }
}

Units and conventions

Bdtcoin Explorer uses backend-native atomic units and UTC-oriented timestamps.

Balance and supply fields ending in Sats are atomic units and may be formatted as BDTC in the frontend.
Fee-rate analytics use jus/vB.
Dates in query strings use YYYY-MM-DD and timestamps return ISO-style strings in UTC context.

Plain-text compatibility routes

Some same-origin frontend aliases intentionally return text/plain instead of JSON for legacy compatibility.

GET /api/unmined-coins, /api/circulating-supply, /api/max-supply, and /api/total-supply return a plain-text string body.
These compatibility values are returned in BDTC, not atomic units.
Each alias is backed by the canonical GET /api/v1/supply payload and extracts one scalar field.

Streaming transport

The live event stream is the realtime transport in the public surface.

GET /api/v1/live/events/stream returns text/event-stream
The server emits named events every five seconds after an initial retry hint
Current event names are summary, mempool_summary, and blocks

retry: 5000

event: summary
data: {...}

event: blocks
data: {...}

Jump to route group

Use these anchors to scan by domain instead of scrolling through the entire API surface.

Service and health

Top-level availability and identity routes outside the /api/v1 explorer namespace.

Blocks

Canonical block listing, detail, latest-block lookup, and block-scoped transaction history.

Transactions

Transaction detail, confirmation status, and raw-hex access.

Addresses

Address detail plus related transaction, UTXO, and balance-history routes.

Holders and labels

Holder leaderboards, distribution views, snapshots, and locked-allocation labeling.

Live and mempool

Realtime explorer snapshots, stream transport, mempool state, and mempool analytics.

Miners and whale analytics

Miner production datasets and whale-transfer analytics endpoints.

Market and supply

Supply state, distribution buckets, and market summary pricing signals.

Network stats

Overview totals plus transaction, address, mining, fee, and block series analytics.

Exact-match search resolution and live suggestion APIs used by the explorer search experience.

Service and health

3 endpoints

Service and health

Top-level availability and identity routes outside the /api/v1 explorer namespace.

GET

Service root

Returns a minimal backend identity payload for quick smoke checks.

ServiceStatusResponse

JSON

ServiceStatusResponse

Simple service metadata object.

Top-level fields

servicestatus

Success example

{
  "service": "bdtexplorer",
  "status": "ok"
}

Error responses

No explicit error branch is documented for this route in the handler.

GET

/health/live

Liveness probe

Reports process liveness and uptime details.

HealthStatus

JSON

HealthStatus

Health payload used by liveness checks.

Top-level fields

statusappNamestartedAtuptimecheckedAt

Success example

{
  "status": "ok",
  "appName": "bdtexplorer-frontend",
  "startedAt": "2026-03-19T20:00:00Z",
  "uptime": "2026-03-19T20:00:00Z",
  "checkedAt": "2026-03-19T20:00:00Z"
}

Error responses

No explicit error branch is documented for this route in the handler.

GET

/health/ready

Readiness probe

Reports readiness with the same shape as the liveness probe.

HealthStatus

JSON

HealthStatus

Health payload used by readiness checks.

Top-level fields

statusappNamestartedAtuptimecheckedAt

Success example

{
  "status": "ok",
  "appName": "bdtexplorer-frontend",
  "startedAt": "2026-03-19T20:00:00Z",
  "uptime": "2026-03-19T20:00:00Z",
  "checkedAt": "2026-03-19T20:00:00Z"
}

Error responses

No explicit error branch is documented for this route in the handler.

Blocks

4 endpoints

Blocks

Canonical block listing, detail, latest-block lookup, and block-scoped transaction history.

GET

/api/v1/blocks

List blocks

Returns canonical blocks ordered newest first.

BlockListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

BlockListResponse

Paginated block list.

Top-level fields

items[]: BlockSummarypagination.limitpagination.offset

Item details

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "items": [
    {
      "height": 0,
      "hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "version": 0,
      "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
      "time": "2026-03-19T20:00:00Z",
      "medianTime": "2026-03-19T20:00:00Z",
      "nonce": 0,
      "bits": 0,
      "difficulty": 0,
      "sizeBytes": 0,
      "weight": 0,
      "txCount": 0,
      "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load blocks

{
  "error": "failed to load blocks"
}

GET

/api/v1/blocks/latest

Latest block

Fetches the current tip block as a singleton response.

BlockSummary

JSON

BlockSummary

Latest canonical block.

Top-level fields

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "height": 0,
  "hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "version": 0,
  "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
  "time": "2026-03-19T20:00:00Z",
  "medianTime": "2026-03-19T20:00:00Z",
  "nonce": 0,
  "bits": 0,
  "difficulty": 0,
  "sizeBytes": 0,
  "weight": 0,
  "txCount": 0,
  "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
}

Error responses

HTTP 404

block not found

{
  "error": "block not found"
}

HTTP 500

failed to load latest block

{
  "error": "failed to load latest block"
}

GET

/api/v1/blocks/{id}

Block detail

Loads one block by height or block hash.

BlockSummary

Parameters

path

string

required

Block height or block hash.

JSON

BlockSummary

Single block summary payload.

Top-level fields

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "height": 0,
  "hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "version": 0,
  "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
  "time": "2026-03-19T20:00:00Z",
  "medianTime": "2026-03-19T20:00:00Z",
  "nonce": 0,
  "bits": 0,
  "difficulty": 0,
  "sizeBytes": 0,
  "weight": 0,
  "txCount": 0,
  "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
}

Error responses

HTTP 400

missing block identifier

{
  "error": "missing block identifier"
}

HTTP 404

block not found

{
  "error": "block not found"
}

HTTP 500

failed to load block

{
  "error": "failed to load block"
}

GET

/api/v1/blocks/{id}/transactions

Block transactions

Returns transaction summaries for a specific block.

TransactionSummaryListResponse

Parameters

path

string

required

Block height or block hash.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

TransactionSummaryListResponse

Paginated transaction summaries scoped to one block.

Top-level fields

items[]: TransactionSummarypagination.limitpagination.offset

Item details

txidblockHeightblockPositionversionlockTimesizeBytesweighttotalInputSatstotalOutputSatsfeeSatsisCoinbase

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "blockHeight": 0,
      "blockPosition": 0,
      "version": 0,
      "lockTime": "2026-03-19T20:00:00Z",
      "sizeBytes": 0,
      "weight": 0,
      "totalInputSats": 0,
      "totalOutputSats": 0,
      "feeSats": 0,
      "isCoinbase": true
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing block identifier, invalid limit, or invalid offset

{
  "error": "missing block identifier, invalid limit, or invalid offset"
}

HTTP 404

block not found

{
  "error": "block not found"
}

HTTP 500

failed to load block transactions

{
  "error": "failed to load block transactions"
}

Transactions

3 endpoints

Transactions

Transaction detail, confirmation status, and raw-hex access.

GET

/api/v1/transactions/{txid}

Transaction detail

Returns a full transaction model including inputs and outputs.

TransactionResponse

Parameters

txid

path

string

required

Transaction identifier.

JSON

TransactionResponse

Full transaction payload.

Top-level fields

txidblockHeightblockPositionversionlockTimesizeBytesweighttotalInputSatstotalOutputSatsfeeSatsisCoinbaseinputs[]outputs[]

Item details

Success example

{
  "txid": "1111111111111111111111111111111111111111111111111111111111111111",
  "blockHeight": 0,
  "blockPosition": 0,
  "version": 0,
  "lockTime": "2026-03-19T20:00:00Z",
  "sizeBytes": 0,
  "weight": 0,
  "totalInputSats": 0,
  "totalOutputSats": 0,
  "feeSats": 0,
  "isCoinbase": true,
  "inputs": [
    {
      "inputIndex": 0,
      "prevTxid": "1111111111111111111111111111111111111111111111111111111111111111",
      "prevOutputIndex": 0,
      "scriptSig": 0,
      "sequence": 0,
      "coinbaseData": 0,
      "valueSats": 0,
      "address": "BdtExampleAddress123"
    }
  ],
  "outputs": [
    {
      "outputIndex": 0,
      "valueSats": 0,
      "scriptPubKey": 0,
      "scriptType": 0,
      "requiredSignatures": 0,
      "address": "BdtExampleAddress123",
      "spentByTxid": "1111111111111111111111111111111111111111111111111111111111111111",
      "spentByInputIndex": 0,
      "spent": 0
    }
  ]
}

Error responses

HTTP 400

missing transaction id

{
  "error": "missing transaction id"
}

HTTP 404

transaction not found

{
  "error": "transaction not found"
}

HTTP 500

failed to load transaction

{
  "error": "failed to load transaction"
}

GET

/api/v1/transactions/{txid}/status

Transaction status

Returns confirmation metadata without the full transaction body.

TransactionStatus

Parameters

txid

path

string

required

Transaction identifier.

JSON

TransactionStatus

Confirmation status payload.

Top-level fields

txidconfirmedblockHeightblockHashblockPosition

Success example

{
  "txid": "1111111111111111111111111111111111111111111111111111111111111111",
  "confirmed": 0,
  "blockHeight": 0,
  "blockHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "blockPosition": 0
}

Error responses

HTTP 400

missing transaction id

{
  "error": "missing transaction id"
}

HTTP 404

transaction not found

{
  "error": "transaction not found"
}

HTTP 500

failed to load transaction status

{
  "error": "failed to load transaction status"
}

GET

/api/v1/transactions/{txid}/raw

Raw transaction hex

Returns the serialized raw transaction hex string.

TransactionRaw

Parameters

txid

path

string

required

Transaction identifier.

JSON

TransactionRaw

Raw transaction payload.

Top-level fields

txidhex

Success example

{
  "txid": "1111111111111111111111111111111111111111111111111111111111111111",
  "hex": 0
}

Error responses

HTTP 400

missing transaction id

{
  "error": "missing transaction id"
}

HTTP 404

transaction not found

{
  "error": "transaction not found"
}

HTTP 500

failed to load raw transaction

{
  "error": "failed to load raw transaction"
}

Addresses

4 endpoints

Addresses

Address detail plus related transaction, UTXO, and balance-history routes.

GET

/api/v1/addresses/{address}

Address detail

Returns aggregate address statistics and first/last seen information.

AddressResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

JSON

AddressResponse

Single address summary.

Top-level fields

addressfirstSeenHeightfirstSeenTxidlastSeenHeightlastSeenTxidoutputCountinputCountfundedSatsspentSatsbalanceSatstxCountreceivedTxCountsentTxCount

Success example

{
  "address": "BdtExampleAddress123",
  "firstSeenHeight": 0,
  "firstSeenTxid": "1111111111111111111111111111111111111111111111111111111111111111",
  "lastSeenHeight": 0,
  "lastSeenTxid": "1111111111111111111111111111111111111111111111111111111111111111",
  "outputCount": 0,
  "inputCount": 0,
  "fundedSats": 0,
  "spentSats": 0,
  "balanceSats": 0,
  "txCount": 0,
  "receivedTxCount": 0,
  "sentTxCount": 0
}

Error responses

HTTP 400

missing address

{
  "error": "missing address"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address

{
  "error": "failed to load address"
}

Notes

Frontend normalization accepts fundedSats and spentSats as either integer JSON values or strings before converting to bigint.

GET

/api/v1/addresses/{address}/transactions

Address transactions

Returns paginated full transaction details touching the address.

TransactionListResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

TransactionListResponse

Paginated full transaction payloads.

Top-level fields

items[]: TransactionResponsepagination.limitpagination.offset

Item details

txidblockHeightblockPositionversionlockTimesizeBytesweighttotalInputSatstotalOutputSatsfeeSatsisCoinbaseinputs[]outputs[]

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "blockHeight": 0,
      "blockPosition": 0,
      "version": 0,
      "lockTime": "2026-03-19T20:00:00Z",
      "sizeBytes": 0,
      "weight": 0,
      "totalInputSats": 0,
      "totalOutputSats": 0,
      "feeSats": 0,
      "isCoinbase": true,
      "inputs": [
        {}
      ],
      "outputs": [
        {}
      ]
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing address, invalid limit, or invalid offset

{
  "error": "missing address, invalid limit, or invalid offset"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address transactions

{
  "error": "failed to load address transactions"
}

GET

/api/v1/addresses/{address}/utxos

Address UTXOs

Returns spendable and historical UTXO records for the address.

AddressUtxoListResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

AddressUtxoListResponse

Paginated UTXO list.

Top-level fields

items[]: AddressUtxopagination.limitpagination.offset

Item details

txidoutputIndexblockHeightvalueSatsscriptPubKeyscriptTyperequiredSignatures

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "outputIndex": 0,
      "blockHeight": 0,
      "valueSats": 0,
      "scriptPubKey": 0,
      "scriptType": 0,
      "requiredSignatures": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing address, invalid limit, or invalid offset

{
  "error": "missing address, invalid limit, or invalid offset"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address utxos

{
  "error": "failed to load address utxos"
}

GET

/api/v1/addresses/{address}/balance-history

Address balance history

Returns historical balance deltas over indexed blocks.

AddressBalanceHistoryResponse

Parameters

address

path

string

required

Base58 or Bech32 address.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

AddressBalanceHistoryResponse

Paginated balance history points.

Top-level fields

items[]: AddressBalanceHistoryPointpagination.limitpagination.offset

Item details

blockHeightblockTimedeltaSatsbalanceSats

Success example

{
  "items": [
    {
      "blockHeight": 0,
      "blockTime": "2026-03-19T20:00:00Z",
      "deltaSats": 0,
      "balanceSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

missing address, invalid limit, or invalid offset

{
  "error": "missing address, invalid limit, or invalid offset"
}

HTTP 404

address not found

{
  "error": "address not found"
}

HTTP 500

failed to load address balance history

{
  "error": "failed to load address balance history"
}

Holders and labels

8 endpoints

Holders and labels

Holder leaderboards, distribution views, snapshots, and locked-allocation labeling.

GET

/api/v1/holders/top

Top holders

Returns paginated positive-balance holder rows.

HolderListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

HolderListResponse

Paginated holder list.

Top-level fields

items[]: Holderpagination.limitpagination.offset

Item details

addressbalanceSatsfundedSatsspentSatstxCountreceivedTxCountsentTxCountfirstSeenHeightlastSeenHeight

Success example

{
  "items": [
    {
      "address": "BdtExampleAddress123",
      "balanceSats": 0,
      "fundedSats": 0,
      "spentSats": 0,
      "txCount": 0,
      "receivedTxCount": 0,
      "sentTxCount": 0,
      "firstSeenHeight": 0,
      "lastSeenHeight": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load holders

{
  "error": "failed to load holders"
}

GET

/api/v1/holders/leaderboard

Combined holder leaderboard

Returns locked allocation rows plus a paginated regular-holder page.

HolderLeaderboardResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

HolderLeaderboardResponse

Composite leaderboard payload.

Top-level fields

lockedAllocations.items[]: LockedAllocationItemlockedAllocations.summary: LockedAllocationSummaryholders.items[]: Holderholders.pagination.limitholders.pagination.offset

Item details

labeladdressbalanceSatsexpectedBalanceSatssharePercentaddressbalanceSatsfundedSatsspentSatstxCountreceivedTxCountsentTxCountfirstSeenHeightlastSeenHeight

Success example

{
  "lockedAllocations": {
    "items": [
      {
        "label": "example",
        "address": "BdtExampleAddress123",
        "balanceSats": 0,
        "expectedBalanceSats": 0,
        "sharePercent": 0,
        "fundedSats": 0,
        "spentSats": 0,
        "txCount": 0,
        "receivedTxCount": 0,
        "sentTxCount": 0,
        "firstSeenHeight": 0,
        "lastSeenHeight": 0
      }
    ],
    "summary": 0
  },
  "holders": {
    "items": [
      {
        "label": "example",
        "address": "BdtExampleAddress123",
        "balanceSats": 0,
        "expectedBalanceSats": 0,
        "sharePercent": 0,
        "fundedSats": 0,
        "spentSats": 0,
        "txCount": 0,
        "receivedTxCount": 0,
        "sentTxCount": 0,
        "firstSeenHeight": 0,
        "lastSeenHeight": 0
      }
    ],
    "pagination": {
      "limit": 0,
      "offset": 0
    }
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load holder leaderboard

{
  "error": "failed to load holder leaderboard"
}

GET

/api/v1/holders/buckets

Holder buckets

Returns holder concentration buckets with tracked balance totals.

HolderDistributionResponse

JSON

HolderDistributionResponse

Bucket distribution payload.

Top-level fields

buckets[]totalHolderCounttotalTrackedBalanceSatsindexedTipHeight

Item details

buckets[].minBalanceSatsbuckets[].maxBalanceSatsbuckets[].openEndedbuckets[].addressCountbuckets[].totalBalanceSats

Success example

{
  "buckets": [
    {
      "minBalanceSats": 0,
      "maxBalanceSats": 0,
      "openEnded": true,
      "addressCount": "BdtExampleAddress123",
      "totalBalanceSats": 0
    }
  ],
  "totalHolderCount": 0,
  "totalTrackedBalanceSats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load holder buckets

{
  "error": "failed to load holder buckets"
}

GET

/api/v1/holders/distribution

Holder distribution

Returns the same bucketed holder-distribution contract used across analytics views.

HolderDistributionResponse

JSON

HolderDistributionResponse

Bucket distribution payload.

Top-level fields

buckets[]totalHolderCounttotalTrackedBalanceSatsindexedTipHeight

Item details

buckets[].minBalanceSatsbuckets[].maxBalanceSatsbuckets[].openEndedbuckets[].addressCountbuckets[].totalBalanceSats

Success example

{
  "buckets": [
    {
      "minBalanceSats": 0,
      "maxBalanceSats": 0,
      "openEnded": true,
      "addressCount": "BdtExampleAddress123",
      "totalBalanceSats": 0
    }
  ],
  "totalHolderCount": 0,
  "totalTrackedBalanceSats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load holder distribution

{
  "error": "failed to load holder distribution"
}

GET

/api/v1/holders/snapshots

Holder snapshots

Returns ranked point-in-time holder snapshots.

HolderSnapshotsResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

HolderSnapshotsResponse

Snapshot payload with pagination.

Top-level fields

items[]: HolderSnapshotItemsnapshotTimetotalHolderCountindexedTipHeightpagination.limitpagination.offset

Item details

addressrankbalanceSatsbucket

Success example

{
  "items": [
    {
      "address": "BdtExampleAddress123",
      "rank": 0,
      "balanceSats": 0,
      "bucket": 0
    }
  ],
  "snapshotTime": "2026-03-19T20:00:00Z",
  "totalHolderCount": 0,
  "indexedTipHeight": 0,
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load holder snapshots

{
  "error": "failed to load holder snapshots"
}

GET

/api/v1/labels/locked-allocation

Locked allocation list

Returns paginated labeled locked-allocation addresses.

LockedAllocationListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

LockedAllocationListResponse

Paginated locked-allocation list.

Top-level fields

items[]: LockedAllocationItempagination.limitpagination.offset

Item details

labeladdressbalanceSatsexpectedBalanceSatssharePercent

Success example

{
  "items": [
    {
      "label": "example",
      "address": "BdtExampleAddress123",
      "balanceSats": 0,
      "expectedBalanceSats": 0,
      "sharePercent": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load locked allocation

{
  "error": "failed to load locked allocation"
}

GET

/api/v1/labels/locked-allocation/summary

Locked allocation summary

Returns aggregate totals for tracked locked-allocation addresses.

LockedAllocationSummary

JSON

LockedAllocationSummary

Aggregate locked-allocation totals.

Top-level fields

totalBalanceSatstotalExpectedBalanceSatslabeledAddressCountindexedTipHeight

Success example

{
  "totalBalanceSats": 0,
  "totalExpectedBalanceSats": 0,
  "labeledAddressCount": "BdtExampleAddress123",
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load locked allocation summary

{
  "error": "failed to load locked allocation summary"
}

GET

/api/v1/labels/locked-allocation/series

Locked allocation series

Returns time-series changes for locked-allocation balances.

LockedAllocationSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

LockedAllocationSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: LockedAllocationSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daynetChangeSatstotalBalanceSats

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "netChangeSats": 0,
      "totalBalanceSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load locked allocation series

{
  "error": "failed to load locked allocation series"
}

Live and mempool

11 endpoints

Live and mempool

Realtime explorer snapshots, stream transport, mempool state, and mempool analytics.

GET

/api/v1/live/summary

Live summary

Returns a compact live snapshot used by streaming and homepage status surfaces.

LiveSummary

JSON

LiveSummary

Current live explorer summary.

Top-level fields

blockCounttransactionCountaddressCounttotalTrackedBalanceSatslatestBlockHeightlatestBlockHashlatestBlockTime

Success example

{
  "blockCount": 0,
  "transactionCount": 0,
  "addressCount": "BdtExampleAddress123",
  "totalTrackedBalanceSats": 0,
  "latestBlockHeight": 0,
  "latestBlockHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "latestBlockTime": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load live summary

{
  "error": "failed to load live summary"
}

GET

/api/v1/live/blocks

Live blocks history

Returns the latest blocks with standard pagination.

BlockListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

BlockListResponse

Paginated recent blocks list.

Top-level fields

items[]: BlockSummarypagination.limitpagination.offset

Item details

heighthashpreviousHashversionmerkleRoottimemedianTimenoncebitsdifficultysizeBytesweighttxCountchainwork

Success example

{
  "items": [
    {
      "height": 0,
      "hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "version": 0,
      "merkleRoot": "0000000000000000000000000000000000000000000000000000000000000000",
      "time": "2026-03-19T20:00:00Z",
      "medianTime": "2026-03-19T20:00:00Z",
      "nonce": 0,
      "bits": 0,
      "difficulty": 0,
      "sizeBytes": 0,
      "weight": 0,
      "txCount": 0,
      "chainwork": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load live blocks

{
  "error": "failed to load live blocks"
}

GET

/api/v1/live/events

Live events history

Returns paginated block-event history using the shared series filter contract.

LiveEventListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

LiveEventListResponse

Paginated event history payload.

Top-level fields

items[]: LiveEventpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

typeblockHeightblockHashblockTimetxCount

Success example

{
  "items": [
    {
      "type": 0,
      "blockHeight": 0,
      "blockHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "blockTime": "2026-03-19T20:00:00Z",
      "txCount": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load live events

{
  "error": "failed to load live events"
}

GET

/api/v1/live/events/stream

Live events stream

Server-sent event stream that pushes summary, mempool, and latest-block snapshots.

LiveEventStream

SSE

LiveEventStream

text/event-stream transport with named JSON payload events.

Top-level fields

Content-Type: text/event-streamCache-Control: no-cacheConnection: keep-aliveretry: 5000 emitted on connect

Emitted events

summary

LiveSummary

mempool_summary

MempoolSummary

blocks

BlockListResponse(limit=5, offset=0)

Success example

retry: 5000

event: summary
data: {"indexedTipHeight": 917135}

event: blocks
data: [{"height": 917135}]

Error responses

HTTP 500

streaming not supported or stream initialization failed

{
  "error": "streaming not supported or stream initialization failed"
}

GET

/api/v1/mempool/summary

Mempool summary

Returns aggregate mempool counts, bytes, and fee totals.

MempoolSummary

JSON

MempoolSummary

Current mempool summary.

Top-level fields

transactionCountbytesusageBytestotalFeeSatsloaded

Success example

{
  "transactionCount": 0,
  "bytes": 0,
  "usageBytes": 0,
  "totalFeeSats": 0,
  "loaded": 0
}

Error responses

HTTP 500

failed to load mempool summary

{
  "error": "failed to load mempool summary"
}

GET

/api/v1/mempool/transactions

Mempool transactions

Returns paginated mempool transactions ordered for explorer listing.

MempoolTransactionListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MempoolTransactionListResponse

Paginated mempool transaction list.

Top-level fields

items[]: MempoolTransactionpagination.limitpagination.offset

Item details

txidvirtualSizeBytesweightfeeSatsmodifiedFeeSatsfeeRateSatPerVByte (jus/vB)timeheightancestorCountdescendantCount

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "virtualSizeBytes": 0,
      "weight": 0,
      "feeSats": 0,
      "modifiedFeeSats": 0,
      "feeRateSatPerVByte": 0,
      "time": "2026-03-19T20:00:00Z",
      "height": 0,
      "ancestorCount": 0,
      "descendantCount": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load mempool transactions

{
  "error": "failed to load mempool transactions"
}

GET

/api/v1/mempool/recent

Recent mempool transactions

Returns the latest mempool arrivals with the same DTO as the full mempool list.

MempoolTransactionListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MempoolTransactionListResponse

Paginated recent mempool transaction list.

Top-level fields

items[]: MempoolTransactionpagination.limitpagination.offset

Item details

txidvirtualSizeBytesfeeSatsfeeRateSatPerVByte (jus/vB)time

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "virtualSizeBytes": 0,
      "feeSats": 0,
      "feeRateSatPerVByte": 0,
      "time": "2026-03-19T20:00:00Z"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load recent mempool transactions

{
  "error": "failed to load recent mempool transactions"
}

GET

/api/v1/mempool/fees

Fee estimates

Returns next-block and short-horizon fee guidance.

MempoolFees

JSON

MempoolFees

Fee estimate summary.

Top-level fields

nextBlock.smartnextBlock.minnextBlock.maxnextBlock.median30min60min1day

Success example

{
  "nextBlock": {
    "smart": 0,
    "min": 0,
    "max": 0,
    "median": 0
  },
  "30min": 0,
  "60min": 0,
  "1day": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load mempool fees

{
  "error": "failed to load mempool fees"
}

GET

/api/v1/mempool/buckets

Fee-rate buckets

Returns mempool composition grouped by fee-rate band.

MempoolFeeRateBucketResponse

JSON

MempoolFeeRateBucketResponse

Bucketed fee-rate analytics.

Top-level fields

items[]: MempoolFeeRateBucket

Item details

minFeeRateSatPerVByte (jus/vB)maxFeeRateSatPerVByte (jus/vB)openEndedtransactionCounttotalVirtualSizeBytestotalFeeSats

Success example

{
  "items": [
    {
      "minFeeRateSatPerVByte": 0,
      "maxFeeRateSatPerVByte": 0,
      "openEnded": true,
      "transactionCount": 0,
      "totalVirtualSizeBytes": 0,
      "totalFeeSats": 0
    }
  ]
}

Error responses

HTTP 500

failed to load mempool fee rate buckets

{
  "error": "failed to load mempool fee rate buckets"
}

GET

/api/v1/mempool/age-distribution

Mempool age distribution

Returns mempool composition grouped by transaction age.

MempoolAgeDistributionResponse

JSON

MempoolAgeDistributionResponse

Bucketed age analytics.

Top-level fields

items[]: MempoolAgeBucket

Item details

minAgeSecondsmaxAgeSecondsopenEndedtransactionCounttotalVirtualSizeBytes

Success example

{
  "items": [
    {
      "minAgeSeconds": 0,
      "maxAgeSeconds": 0,
      "openEnded": true,
      "transactionCount": 0,
      "totalVirtualSizeBytes": 0
    }
  ]
}

Error responses

HTTP 500

failed to load mempool age distribution

{
  "error": "failed to load mempool age distribution"
}

GET

/api/v1/mempool/size-distribution

Mempool size distribution

Returns mempool composition grouped by virtual-size band.

MempoolSizeDistributionResponse

JSON

MempoolSizeDistributionResponse

Bucketed size analytics.

Top-level fields

items[]: MempoolSizeBucket

Item details

minVirtualSizeBytesmaxVirtualSizeBytesopenEndedtransactionCounttotalVirtualSizeBytes

Success example

{
  "items": [
    {
      "minVirtualSizeBytes": 0,
      "maxVirtualSizeBytes": 0,
      "openEnded": true,
      "transactionCount": 0,
      "totalVirtualSizeBytes": 0
    }
  ]
}

Error responses

HTTP 500

failed to load mempool size distribution

{
  "error": "failed to load mempool size distribution"
}

Miners and whale analytics

7 endpoints

Miners and whale analytics

Miner production datasets and whale-transfer analytics endpoints.

GET

/api/v1/miners/summary

Miner summary

Returns miner ranking and network share totals.

MinerSummaryResponse

JSON

MinerSummaryResponse

Miner summary payload.

Top-level fields

items[]: MinerSummaryItemtotalMinerCounttotalMinedBlockCountindexedTipHeight

Item details

minerNameblockCounttotalRewardSatssharePercentlatestBlockHeightlatestBlockTime

Success example

{
  "items": [
    {
      "minerName": "example",
      "blockCount": 0,
      "totalRewardSats": 0,
      "sharePercent": 0,
      "latestBlockHeight": 0,
      "latestBlockTime": "2026-03-19T20:00:00Z"
    }
  ],
  "totalMinerCount": 0,
  "totalMinedBlockCount": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load miners summary

{
  "error": "failed to load miners summary"
}

GET

/api/v1/miners/compare

Compare miners

Returns paginated miner detail rows and optionally filters by repeated name query params.

MinerCompareResponse

Parameters

name

query

string[]

Repeatable miner name filter.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MinerCompareResponse

Paginated miner comparison list.

Top-level fields

items[]: MinerDetailBasepagination.limitpagination.offset

Item details

minerNameblockCounttotalRewardSatssharePercentlatestBlockHeightlatestBlockTimeaverageRewardSatsindexedTipHeight

Success example

{
  "items": [
    {
      "minerName": "example",
      "blockCount": 0,
      "totalRewardSats": 0,
      "sharePercent": 0,
      "latestBlockHeight": 0,
      "latestBlockTime": "2026-03-19T20:00:00Z",
      "averageRewardSats": 0,
      "indexedTipHeight": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 404

miner not found

{
  "error": "miner not found"
}

HTTP 500

failed to compare miners

{
  "error": "failed to compare miners"
}

GET

/api/v1/miners/series

Miner series

Returns paginated daily miner production rows.

MinerSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MinerSeriesResponse

Paginated miner series payload.

Top-level fields

items[]: MinerSeriesPointpagination.limitpagination.offset

Item details

dayminerNameblockCounttotalRewardSats

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "minerName": "example",
      "blockCount": 0,
      "totalRewardSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load miner series

{
  "error": "failed to load miner series"
}

GET

/api/v1/miners/{name}

Miner detail

Returns a miner detail row and optionally nests dailySeries when include=dailySeries is present.

MinerDetailResponse

Parameters

name

path

string

required

Miner name.

include

query

dailySeries

Optional nested daily-series include.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

MinerDetailResponse

Miner detail payload with optional nested dailySeries list.

Top-level fields

minerNameblockCounttotalRewardSatssharePercentlatestBlockHeightlatestBlockTimeaverageRewardSatsindexedTipHeightdailySeries?: { items[], pagination }

Item details

dailySeries.items[].daydailySeries.items[].blockCountdailySeries.items[].totalRewardSats

Success example

{
  "minerName": "example",
  "blockCount": 0,
  "totalRewardSats": 0,
  "sharePercent": 0,
  "latestBlockHeight": 0,
  "latestBlockTime": "2026-03-19T20:00:00Z",
  "averageRewardSats": 0,
  "indexedTipHeight": 0,
  "dailySeries": {
    "items": [
      {
        "day": "2026-03-19T20:00:00Z",
        "blockCount": 0,
        "totalRewardSats": 0
      }
    ],
    "pagination": 0
  }
}

Error responses

HTTP 400

invalid include, limit, or offset

{
  "error": "invalid include, limit, or offset"
}

HTTP 404

miner not found

{
  "error": "miner not found"
}

HTTP 500

failed to load miner detail

{
  "error": "failed to load miner detail"
}

GET

/api/v1/analytics/whales/events

Whale events

Returns paginated whale transfer events above the configured backend threshold.

WhaleEventListResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

WhaleEventListResponse

Paginated whale event list.

Top-level fields

items[]: WhaleEventpagination.limitpagination.offset

Item details

txidoutputIndexblockHeightblockTimeaddressvalueSats

Success example

{
  "items": [
    {
      "txid": "1111111111111111111111111111111111111111111111111111111111111111",
      "outputIndex": 0,
      "blockHeight": 0,
      "blockTime": "2026-03-19T20:00:00Z",
      "address": "BdtExampleAddress123",
      "valueSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}

Error responses

HTTP 400

invalid limit or invalid offset

{
  "error": "invalid limit or invalid offset"
}

HTTP 500

failed to load whale events

{
  "error": "failed to load whale events"
}

GET

/api/v1/analytics/whales/summary

Whale summary

Returns summary metrics and optionally latestEvents when include=latestEvents is requested.

WhaleSummaryResponse

Parameters

include

query

latestEvents

Optional nested latest whale events include.

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

JSON

WhaleSummaryResponse

Whale summary payload with optional nested latestEvents list.

Top-level fields

eventCounttotalValueSatsuniqueAddressCountindexedTipHeightthresholdSatslatestEvents?: { items[], pagination }

Item details

latestEvents.items[].txidlatestEvents.items[].blockHeightlatestEvents.items[].addresslatestEvents.items[].valueSats

Success example

{
  "eventCount": 0,
  "totalValueSats": 0,
  "uniqueAddressCount": "BdtExampleAddress123",
  "indexedTipHeight": 0,
  "thresholdSats": 0,
  "latestEvents": {
    "items": [
      {
        "txid": "1111111111111111111111111111111111111111111111111111111111111111",
        "blockHeight": 0,
        "address": "BdtExampleAddress123",
        "valueSats": 0
      }
    ],
    "pagination": 0
  }
}

Error responses

HTTP 400

invalid include, limit, or offset

{
  "error": "invalid include, limit, or offset"
}

HTTP 500

failed to load whale summary

{
  "error": "failed to load whale summary"
}

GET

/api/v1/analytics/whales/series

Whale series

Returns whale-event totals over time using shared series filters.

WhaleSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

WhaleSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: WhaleSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

dayeventCounttotalValueSats

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "eventCount": 0,
      "totalValueSats": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load whale series

{
  "error": "failed to load whale series"
}

Market and supply

7 endpoints

Market and supply

Supply state, distribution buckets, and market summary pricing signals.

GET

/api/v1/market/summary

Market summary

Returns current exchange-rate and market-cap style metrics.

MarketSummary

JSON

MarketSummary

Market snapshot payload.

Top-level fields

exchangeRatemarketCapgoldRatevolume24hcurrencyupdatedAt

Success example

{
  "exchangeRate": 0,
  "marketCap": 0,
  "goldRate": 0,
  "volume24h": 0,
  "currency": "USD",
  "updatedAt": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load market summary

{
  "error": "failed to load market summary"
}

GET

/api/v1/supply

Supply summary

Returns issued, mined, total, max, circulating, unmined, and locked supply totals.

SupplySummary

JSON

SupplySummary

Supply state payload.

Top-level fields

issuedSupplySatsunspentSupplySatsunspentOutputCountindexedTipHeightmaxSupplySatstotalSupplySatstotalMinedSatscirculatingSupplySatsunminedSupplySatslockedAllocationSats

Success example

{
  "issuedSupplySats": 0,
  "unspentSupplySats": 0,
  "unspentOutputCount": 0,
  "indexedTipHeight": 0,
  "maxSupplySats": 0,
  "totalSupplySats": 0,
  "totalMinedSats": 0,
  "circulatingSupplySats": 0,
  "unminedSupplySats": 0,
  "lockedAllocationSats": 0
}

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

GET

/api/v1/supply/distribution

Supply distribution

Returns supply concentration buckets across tracked balances.

SupplyDistribution

JSON

SupplyDistribution

Bucketed supply distribution payload.

Top-level fields

buckets[]totalTrackedSupplySatsindexedTipHeight

Item details

buckets[].minBalanceSatsbuckets[].maxBalanceSatsbuckets[].openEndedbuckets[].addressCountbuckets[].totalBalanceSats

Success example

{
  "buckets": [
    {
      "minBalanceSats": 0,
      "maxBalanceSats": 0,
      "openEnded": true,
      "addressCount": "BdtExampleAddress123",
      "totalBalanceSats": 0
    }
  ],
  "totalTrackedSupplySats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load supply distribution

{
  "error": "failed to load supply distribution"
}

GET

/api/unmined-coins

Unmined coins alias

Returns the remaining mineable supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> unminedSupplySats.
Response body is plain text in BDTC, not a JSON object and not atomic units.

GET

/api/circulating-supply

Circulating supply alias

Returns circulating supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> circulatingSupplySats.
Response body is plain text in BDTC, not a JSON object and not atomic units.

GET

/api/max-supply

Max supply alias

Returns the protocol max supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> maxSupplySats.
Response body is plain text in BDTC, not a JSON object and not atomic units.

GET

/api/total-supply

Total supply alias

Returns total supply as a same-origin plain-text coin value sourced from the canonical supply summary.

PlainTextCoinValue

TEXT

PlainTextCoinValue

Plain-text coin value.

Top-level fields

body: string coin value

Success example

71000000

Error responses

HTTP 500

failed to load supply summary

{
  "error": "failed to load supply summary"
}

Notes

Backed by GET /api/v1/supply -> totalSupplySats.
Under the current supply contract this matches max supply. Response body is plain text in BDTC, not a JSON object and not atomic units.

Network stats

9 endpoints

Network stats

Overview totals plus transaction, address, mining, fee, and block series analytics.

GET

/api/v1/stats/overview

Overview stats

Returns top-level indexed chain totals.

StatsOverview

JSON

StatsOverview

Overview metric payload.

Top-level fields

blockCounttransactionCountaddressCountindexedTipHeight

Success example

{
  "blockCount": 0,
  "transactionCount": 0,
  "addressCount": "BdtExampleAddress123",
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load stats overview

{
  "error": "failed to load stats overview"
}

GET

/api/v1/stats/transactions

Transaction stats

Returns aggregate transaction metrics.

StatsTransactions

JSON

StatsTransactions

Transaction metrics payload.

Top-level fields

transactionCountcoinbaseTransactionCountnonCoinbaseTransactionCounttotalFeesSatsaverageFeeSatsaverageSizeBytesaverageWeightindexedTipHeight

Success example

{
  "transactionCount": 0,
  "coinbaseTransactionCount": 0,
  "nonCoinbaseTransactionCount": 0,
  "totalFeesSats": 0,
  "averageFeeSats": 0,
  "averageSizeBytes": 0,
  "averageWeight": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load transaction stats

{
  "error": "failed to load transaction stats"
}

GET

/api/v1/stats/transactions/series

Transaction series

Returns transaction metrics over time.

StatsTransactionsSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsTransactionsSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsTransactionsSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daytransactionCountcoinbaseTransactionCountnonCoinbaseTransactionCounttotalFeesSatsaverageFeeSatsaverageSizeBytesaverageWeight

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "transactionCount": 0,
      "coinbaseTransactionCount": 0,
      "nonCoinbaseTransactionCount": 0,
      "totalFeesSats": 0,
      "averageFeeSats": 0,
      "averageSizeBytes": 0,
      "averageWeight": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load transaction stats series

{
  "error": "failed to load transaction stats series"
}

GET

/api/v1/stats/addresses

Address stats

Returns indexed address and balance totals.

StatsAddresses

JSON

StatsAddresses

Address metrics payload.

Top-level fields

addressCountfundedAddressCountzeroBalanceAddressCounttotalTrackedBalanceSatstotalFundedSatstotalSpentSatsindexedTipHeight

Success example

{
  "addressCount": "BdtExampleAddress123",
  "fundedAddressCount": "BdtExampleAddress123",
  "zeroBalanceAddressCount": "BdtExampleAddress123",
  "totalTrackedBalanceSats": 0,
  "totalFundedSats": 0,
  "totalSpentSats": 0,
  "indexedTipHeight": 0
}

Error responses

HTTP 500

failed to load address stats

{
  "error": "failed to load address stats"
}

GET

/api/v1/stats/addresses/series

Address series

Returns address-growth and address-activity metrics over time.

StatsAddressesSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsAddressesSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsAddressesSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daynewAddressCountcumulativeAddressCountactiveAddressCountreceivingAddressCountsendingAddressCount

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "newAddressCount": "BdtExampleAddress123",
      "cumulativeAddressCount": "BdtExampleAddress123",
      "activeAddressCount": "BdtExampleAddress123",
      "receivingAddressCount": "BdtExampleAddress123",
      "sendingAddressCount": "BdtExampleAddress123"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load address stats series

{
  "error": "failed to load address stats series"
}

GET

/api/v1/stats/mining

Mining stats

Returns aggregate block-production metrics.

StatsMining

JSON

StatsMining

Mining metric payload.

Top-level fields

blockCountaverageBlockSizeBytesaverageBlockWeightaverageTransactionsPerBlocklatestBlockHeightlatestBlockTime

Success example

{
  "blockCount": 0,
  "averageBlockSizeBytes": 0,
  "averageBlockWeight": 0,
  "averageTransactionsPerBlock": 0,
  "latestBlockHeight": 0,
  "latestBlockTime": "2026-03-19T20:00:00Z"
}

Error responses

HTTP 500

failed to load mining stats

{
  "error": "failed to load mining stats"
}

GET

/api/v1/stats/mining/series

Mining series

Returns mining metrics over time.

StatsMiningSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsMiningSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsMiningSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

dayblockCountaverageBlockSizeBytesaverageBlockWeightaverageTransactionsPerBlock

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "blockCount": 0,
      "averageBlockSizeBytes": 0,
      "averageBlockWeight": 0,
      "averageTransactionsPerBlock": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load mining stats series

{
  "error": "failed to load mining stats series"
}

GET

/api/v1/stats/fees/series

Fee series

Returns fee totals and fee-rate averages over time.

StatsFeesSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsFeesSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsFeesSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

daytotalFeesSatsaverageFeeSatsaverageFeeRateSatPerVByte (jus/vB)

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "totalFeesSats": 0,
      "averageFeeSats": 0,
      "averageFeeRateSatPerVByte": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load fee stats series

{
  "error": "failed to load fee stats series"
}

GET

/api/v1/stats/blocks/series

Block series

Returns block-production and interval metrics over time.

StatsBlocksSeriesResponse

Parameters

limit

query

integer

Page size. Defaults to 20.

offset

query

integer

Zero-based result offset. Defaults to 0.

from

query

YYYY-MM-DD

Inclusive UTC start date.

query

YYYY-MM-DD

Inclusive UTC end date.

range

query

7d | 30d | 90d | 365d | all

Predefined UTC time window.

interval

query

day | week | month

Series aggregation interval.

JSON

StatsBlocksSeriesResponse

Series payload with shared filters.

Top-level fields

items[]: StatsBlocksSeriesPointpagination.limitpagination.offsetfilters.fromfilters.tofilters.rangefilters.interval

Item details

dayblockCountaverageBlockSizeBytesaverageBlockWeightaverageTransactionsPerBlockaverageDifficultyaverageBlockIntervalSeconds

Success example

{
  "items": [
    {
      "day": "2026-03-19T20:00:00Z",
      "blockCount": 0,
      "averageBlockSizeBytes": 0,
      "averageBlockWeight": 0,
      "averageTransactionsPerBlock": 0,
      "averageDifficulty": 0,
      "averageBlockIntervalSeconds": "example"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "filters": {
    "from": 0,
    "to": 0,
    "range": "example",
    "interval": "example"
  }
}

Error responses

HTTP 400

invalid limit, offset, from, to, range, or interval

{
  "error": "invalid limit, offset, from, to, range, or interval"
}

HTTP 500

failed to load block stats series

{
  "error": "failed to load block stats series"
}

2 endpoints

Search

Exact-match search resolution and live suggestion APIs used by the explorer search experience.

GET

/api/v1/search

Resolve search query

Attempts to resolve a query into one exact block, transaction, or address result.

SearchResponse

Parameters

query

string

required

Search query string.

JSON

SearchResponse

Single exact-match search result.

Top-level fields

querytypeidpathfound

Success example

{
  "query": 0,
  "type": 0,
  "id": 0,
  "path": 0,
  "found": 0
}

Error responses

HTTP 400

missing search query

{
  "error": "missing search query"
}

HTTP 404

search result not found

{
  "error": "search result not found"
}

HTTP 500

failed to resolve search query

{
  "error": "failed to resolve search query"
}

GET

/api/v1/search/suggest

Search suggestions

Returns a lightweight suggestion list for partial search input.

SearchSuggestionListResponse

Parameters

query

string

required

Search query string.

limit

query

integer

Maximum suggestion count. Defaults to 5.

JSON

SearchSuggestionListResponse

Suggestion list payload.

Top-level fields

items[]: SearchSuggestion

Item details

typeidpathlabel

Success example

{
  "items": [
    {
      "type": 0,
      "id": 0,
      "path": 0,
      "label": "example"
    }
  ]
}

Error responses

HTTP 400

missing search query

{
  "error": "missing search query"
}

HTTP 400

invalid limit

{
  "error": "invalid limit"
}

HTTP 500

failed to load search suggestions

{
  "error": "failed to load search suggestions"
}