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.
?block_number_start=1000&block_number_end=2000
To scan every single block, specify "0" as the starting point and "latest" as the final point.
?block_number_start=0&block_number_end=latest
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.
?block_number_start=17087509&block_number_end=17087509
OR
?block_number_start=-1&block_number_end=-1
For getting the latest block, refer to the Get Single Latest Block endpoint.
block_number_start
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
block_number_end
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.
?timestamp_start=1640995200×tamp_end=1643673540
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.
?timestamp_start=1681991771×tamp_end=1681991771
timestamp_start
accepted values:
"1681991771" (UNIX timestamp) -> the starting timestamp for scanning
timestamp_end
accepted values:
"1681991772" (UNIX timestamp) -> the ending timestamp for scanning
Block_hash
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:
?block_hash=0x0c195cccdaf1c289879187a819ae8caed341fd5568e32d98b584c37dc09c59e7
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.
?offset=000000000069e99f-000a-00000001