Get Block List or Single Block Detail
1. Overview & Typical Use
Paginated query of the block list, or retrieve detailed information for a single block by block number. Supports filtering by Super Representative address and time range.
- Typical use: block explorer list page, query block details by block number, query block production records by SR.
- When not to use: for block statistics summaries use “Get Block Statistics”; for transaction lists use “Get Transaction List”.
2. Endpoint & Authentication
GET /api/block
For Base URL and authentication, see Common Network & Authentication.
3. Request
Fields
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start | integer | No | 0 | Starting offset; start + limit ≤ 10000 |
limit | integer | No | 10 | Page size, max 50 |
number | integer | No | — | Block number. When provided, returns the detail for that single block and ignores time range parameters |
producer | string | No | — | Super Representative address, filter by block producer |
sort | string | No | -number | Sort field; only block number sorting is supported; - prefix means descending |
start_timestamp | integer | No | 0 | Start timestamp (milliseconds) |
end_timestamp | integer | No | Current time | End timestamp (milliseconds) |
count | boolean | No | false | Whether to count and return the total; affects the rangeTotal field |
4. Response
Fields
Top-level
| Field | Type | Required | Description | Unit/Precision |
|---|---|---|---|---|
total | integer | Required | Total matched records (capped at 10000) | — |
rangeTotal | integer | Required | Total blocks within the filtered range | — |
data | array | Required | Block list | — |
data[] elements
| Field | Type | Required | Description | Unit/Precision |
|---|---|---|---|---|
number | integer | Required | Block number | — |
hash | string | Required | Block hash | — |
size | integer | Required | Block size | Bytes |
timestamp | integer | Required | Block time | ms timestamp |
txTrieRoot | string | Required | Transaction Trie root hash | — |
parentHash | string | Required | Parent block hash | — |
witnessId | integer | Required | Block-producing SR ID | — |
witnessAddress | string | Required | Block-producing SR address | — |
witnessName | string | Required | Block-producing SR name | — |
version | integer | Required | Block version number | — |
nrOfTrx | integer | Required | Number of transactions in the block | — |
fee | number | Required | Total block fees | TRX |
confirmed | boolean | Required | Whether confirmed | — |
confirmations | integer | Required | Confirmation count | — |
netUsage | integer | Required | Total bandwidth consumed | — |
energyUsage | integer | Required | Total energy consumed | — |
OtherFeeTrx | number | Required | Other fees | TRX |
otherFeeMap | object | Optional | Other fee breakdown map (may be empty object); returned for single-block queries (number=X); not returned for list queries | — |
bandwidthConsumedFromBurnCnt | integer | Required | Number of transactions consuming bandwidth via burn | — |
freeBandwidthUsageCnt | integer | Required | Number of transactions using free bandwidth | — |
bandwidthBurnFeeSunAmt | integer | Required | Bandwidth burn fee | sun |
energyConsumedFromOwnerBurnCnt | integer | Required | Number of transactions where contract deployer bears energy burn | — |
freeEnergyUsageCnt | integer | Required | Number of transactions using free energy | — |
energyBurnFeeSunAmt | integer | Required | Energy burn fee | sun |
blockReward | number | Required | Block production reward | TRX |
voteReward | number | Required | Voting reward | TRX |
revert | boolean | Required | Whether reverted | — |
trxAnd10TransferCount | integer | Optional | TRX and TRC10 transfer count (returned for single-block queries) | — |
trc20And721TransferCount | integer | Optional | TRC20 and TRC721 transfer count (returned for single-block queries) | — |
trc1155TransferCount | integer | Optional | TRC1155 transfer count (returned for single-block queries) | — |
transferCount | integer | Optional | Total transfer count (returned for single-block queries) | — |
failTxCount | integer | Optional | Failed transaction count (returned for single-block queries) | — |
internalTxCount | integer | Optional | Internal transaction count (returned for single-block queries) | — |
internalParentTxCount | integer | Optional | Number of parent transactions containing internal transactions (returned for single-block queries) | — |
contractTypeDistribute | object | Optional | Distribution of contract types and their transaction counts (returned for single-block queries) | — |
srConfirmList | array | Optional | SR confirmation list (returned for single-block queries) | — |
5. Errors
For HTTP status codes, see Common Errors. Notes for this endpoint:
start + limitexceeds 10000: excess is silently truncated and200is returned; no error is raised.numberdoes not exist: returns200+data: []; no 4xx error.- Empty result is not an error: no matched records returns
200+data: [], which is a normal response.
Last updated on: