As blockchain purists know, time is counted in blocks, not seconds. If it were otherwise, the network of computers that make up the blockchain would have to stay in perfect sync. This isn't possible.
Many API calls allow the user to pass in either a block number or a Unix timestamp (number of seconds since January 1, 1970). We don't love this design, but believe it's necessary for two reasons:
  1. 1.
    "Normal" developers and normal users – and we don't mean that in a derogatory way! – don't think in terms of blocks. They think in terms of time. Even purists might be confused if they were shown a chart with block numbers on the x-axis instead of time. So even though blocks are the true measure of time, human beings think in terms of seconds (minutes, hours, days, etc.)
  2. 2.
    Block numbers are not consistent across chains. We plan to introduce API endpoints that process data on more than one chain. In a multi-chain context, block numbers are meaningless. In those cases only a timestamp will be allowed.
When it comes to time, all of our API endpoints follow a few simple rules:
  • When possible, we allow developers to pass either a block number or a timestamp.
  • If a developer mistakenly passes both, the call will return a 400 response code with message "Only one of {blockNumber} or {timestamp} can be set."