When using our Tsunami API endpoints, you have to specify in what block or time range you want to get the data. (for example, in the Get Blocks endpoint, Get Wallet Transactions endpoint, etc.)

We support setting up the range via:

1. block_numbers,
2. timestamps,
3. block_hash

Learn more about each range below.

---

Block_number range

Use the block_number_start and block_number_end, when you know specific block numbers. This will tell the API what blocks to scan on the blockchain. Note that the end block can't be set to an earlier block than the start block.

These parameters accept int256 values. If you want to set the range to the latest block on the blockchain, set the value as latest.

Also, these parameters accept negative numbers. For example, setting it to block_number_start=-1000 will mean that the starting point is 1000 blocks away from the latest block.

So, to scan from the 1000th block to the 2000th block, we need to set the block_number parameters in the request as

?block_number_start=1000&block_number_end=2000

And if you want to scan every single block, set the starting point as 0 and latest at the end

?block_number_start=0&block_number_end=latest

What if you know the block number and you want to get its time and hash? Simply set the block number start and end to the same block. It will return the block data as well as its timestamp and hash.

?block_number_start=17087509&block_number_end=17087509

OR

?block_number_start=-1&block_number_end=-1

If you want to get simply the latest block - refer to our Single Latest Block endpoint.

📘

Which block_number range to use?

If you are unsure which blockrange to use - use from -100000 to latest.
It might be tempting to set the block_number_start to 0 and block_number_end to latest (this way you request data from genesis block to latest block - years of data). However we would NOT recommend it, unless you know you need excatly that. You would reach your limits quite quickly this way.

---

Timestamp range

If you know the time when your block was produced, you can set the range as timestamps: timestamp_start and timestamp_end.

📘

Use Unix timestamp

Timestamps are represented in UNIX Epoch Time, so you will need to convert your desired time period to UNIX time. Many programming languages support libraries to convert datetime to UNIX time. Alternatively convert the time to Unix, for example, here

Let's say, you want to get the info about the transfers of Address X from January 1st 2022 00:00 GMT to January 31st 2022 23:59 GMT. In UNIX Epoch time it will look like this: 1640995200 and 1643673540.

?timestamp_start=1640995200&timestamp_end=1643673540

If you know the block timestamp and want to get its block number and hash? Simply set the timestamp start and end to the same time. It will return the block data as well as its number and hash.

?timestamp_start=1681991771&timestamp_end=1681991771

📘

The endpoint will collect the blocks within the timestamp range.

---

Block_hash

Use this if you want to get the information in one specific block, use block_hash as one of your request's parameters.

So, you want to get the info in block 1337 on Ethereum. The hash for this block is 0x0c195cccdaf1c289879187a819ae8caed341fd5568e32d98b584c37dc09c59e7 and the parameter will look like this:

?block_hash=0x0c195cccdaf1c289879187a819ae8caed341fd5568e32d98b584c37dc09c59e7

---

Range offset

In many requests, you can observe the range parameter.

Imagine that you are getting data on a very active Smart Contract. You've set the range parameters and a limit of 1000 results. The response always starts with range parameters, where we can gain useful information

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

"has_more": true means there are more than 1000 results on that Smart Contract in this time period. To see the next "page", we need to set the offset parameter in our request to the same value as range.next_offset in the previous response.

So it will look like this:

?offset=000000000069e99f-000a-00000001