Unix Timestamp Converter

Working with Unix time

Unix time counts seconds since the epoch, 1 January 1970 UTC. Because it carries no timezone, it is the standard way systems exchange a point in time. Ethereum block headers use it too: the timestamp field is Unix seconds, so you can paste a block timestamp above to see when that block was produced.

Watch the digit count: a 10-digit number is almost certainly seconds, a 13-digit number is milliseconds. Pick the matching unit so the date comes out right.

Block timestamps since the merge

Proof of work made block times a probability distribution; proof of stake makes them a schedule. Slots are exactly 12 seconds long and every block belongs to a slot, so consecutive timestamps differ by 12 seconds, or by a multiple of 12 when a proposer misses its turn and the slot goes empty. That is what makes time to block number a calculation rather than a search.

Two rules constrain the value. It must be strictly greater than the parent's timestamp, so the sequence never goes backwards, and the proposer chooses it, so it can sit slightly ahead of real time. In practice it is accurate to within a slot. That is fine for charting, ordering and daily aggregation, and it is not fine for anything where a few seconds of proposer discretion is worth money.

// The Beacon Chain genesis, and the slot clock everything hangs off.
const GENESIS = 1606824023;  // 2020-12-01 12:00:23 UTC
const SLOT    = 12;          // seconds

const slotAt = (unixSeconds) => Math.floor((unixSeconds - GENESIS) / SLOT);

// Blocks lag slots slightly because missed slots produce no block,
// so this is an upper bound you then walk down.
slotAt(1735689600); // 2025-01-01 00:00:00 UTC

Finding the block at a point in time

The naive approach is a binary search over the whole chain, which costs about 25 calls to eth_getBlockByNumber and is what most snippets on the internet do. Because the slot clock is fixed you can do far better: estimate, measure the error, correct, and repeat. It converges in two or three calls.

import { WebSocketProvider } from "ethers";

// Inside a BLAZED.sh container or script this is the co-located node.
const provider = new WebSocketProvider("ws://eth:8545");

async function blockAt(targetSeconds) {
  let block = await provider.getBlock("latest");

  // Each pass uses the real 12s cadence to jump most of the remaining gap.
  for (let i = 0; i < 6; i++) {
    const drift = block.timestamp - targetSeconds;
    if (Math.abs(drift) <= 12) break;
    const guess = block.number - Math.round(drift / 12);
    block = await provider.getBlock(Math.max(guess, 1));
  }

  // Walk the last slot or two to land on the first block at or after target.
  while (block.timestamp > targetSeconds) {
    block = await provider.getBlock(block.number - 1);
  }
  return block;
}

Every iteration is a round trip, which is why this pattern feels different depending on where the node is. Against a public gateway each pass costs 50 to 500 milliseconds and counts against a rate limit, so backfilling a year of daily boundaries turns into a job you have to babysit. On a co-located node the same loop runs over a Unix socket in single digit milliseconds, and the calls draw predictable per-request credits instead of an opaque compute unit. The eth_getBlockByNumber reference documents the response shape, and the timestamps in it arrive as hex quantities, which the hex converter turns back into the seconds you can paste above.

Frequently asked questions