Learn how to use ranges with block_numbers, timestamps, and block_hash

When using the Tsunami API endpoints, e.g., "Get Blocks" or "Get Wallet Transactions", you must specify the block or time range you want to retrieve data from. Ranges can be set via "block_numbers", "timestamps" or "block_hash".

Block_number range

When you know specific block numbers, you can utilize the "block_number_start" and "block_number_end" parameters. These are instructions for the API to determine which blocks to scan on the blockchain. Remember that the ending block value must exceed the starting block value.

These parameters accept "int256" values. To set the range to the latest block, enter the value "latest". Alternatively, they take on negative numbers as values. For instance, setting it to "block_number_start=-1000" means the starting point is 1000 blocks away from the latest block.

To scan from block 1000 to block 2000, set the "block_number" parameters in the request.


To scan every single block, specify "0" as the starting point and "latest" as the final point.


Knowing the block number, extract its time and hash by passing the same block number to "block_number_start" and "block_number_end". It returns the block data, timestamp, and hash.




For getting the latest block, refer to the Get Single Latest Block endpoint.


accepted values:

"15537351" -> the starting block for scanning
"latest" -> to get the latest block
"1", "-2", etc. -> to get one or two blocks before the latest


accepted values:

"15537353" -> the ending block for scanning
"latest" -> to get the latest block
"-1", "-2", etc. -> to get one or two blocks before the latest


When unsure what block range to input, try using a range of "-100000" to "latest". As tempting as it might be to set "block_number_start" to "0" and "block_number_end" to "latest", we would recommend against it unless it is exactly what you require. As you would quickly reach your limit due to retrieving data from the genesis to the latest blocks, which is years of data.

Timestamp range

Knowing the time of block production, you may set the range via "timestamp_start" and "timestamp_end". Timestamps are represented in UNIX time, so it is necessary to convert the desired time period to UNIX time. Many programming languages support libraries for datetime conversion. As an alternative, change the time here.

As an example, if you need the information on a contract dated from January 1st, 2022, 00:00 GMT to January 31st, 2022, 23:59 GMT, the actual parameter values would be "1640995200" and "1643673540" in UNIX time.


You can get the block number and hash knowing its timestamp by setting "timestamp_start" and "timestamp_end" to the same time. It returns the block data, number, and hash.



accepted values:

"1681991771" (UNIX timestamp) -> the starting timestamp for scanning


accepted values:

"1681991772" (UNIX timestamp) -> the ending timestamp for scanning


To obtain the data of a specific block, provide its "block_hash" as a parameter value. For instance, the hash of block 1337 on Ethereum, which is "0x0c195cccdaf1c289879187a819ae8caed341fd5568e32d98b584c37dc09c59e7", would structure the parameter like this:


Range offset

When making requests, you can observe the "range" parameter. It is essential when retrieving data from a particularly active smart contract. Setting the range parameters and a limit of 1000 results, the response always begins with key-value pairs within the "range" containing helpful information.

    "range": {
        "has_more": true,
        "start_block": 1,
        "end_block": 6946724,
        "next_offset": "000000000069e99f-000a-00000001"

The key-value pair "has_more": true means there are more than 1000 results on that smart contract in a given period. To see the next page, set the "offset" parameter to the same value as in "range": {"next_offset": "000000000069e99f-000a-00000001"} in the previous response.