Block Timestamps

Time on Polygon is whatever the block says it is: a Bor block carries a single timestamp field, and any contract that reads block.timestamp — for vesting, auctions, staking rewards, or time-locked withdrawals — is trusting the validator that produced that block. With a new block every ~2 seconds on chain 137 the timestamp usually tracks wall-clock time closely, but it is set by the proposer, not by an authoritative clock, so it can be nudged within protocol bounds and can drift from your server's time. This guide is for smart contract and backend developers who depend on on-chain time; it covers how Polygon timestamps are produced, their accuracy limits, how far a validator can move them, and how to write time-sensitive logic that stays safe. Examples read blocks from https://polygon.therpc.io/YOUR_API_KEY.

Understanding Block Timestamps

• Who sets them: The Bor validator that proposes a block sets its timestamp, expressed as Unix seconds. It is the proposer's declared time, not a reading from a trusted global clock, and it is what your contract sees as block.timestamp.
• Accuracy guarantees: Polygon gives you a loosely accurate clock, not a precise one. The protocol requires each block's timestamp to be greater than its parent's and roughly aligned with the ~2s cadence, so timestamps move forward in step with real time on average — but there is no guarantee of sub-second or even second-level precision for any individual block.
• Manipulation bounds: A proposer can choose a timestamp within a permitted window — it must exceed the parent block's timestamp and cannot jump unreasonably far ahead of real time. That leaves room to shift it by a few seconds. This is harmless for coarse logic but unsafe if a few seconds of slack lets someone game a deadline, an auction close, or a randomness seed on chain 137.
• Network time drift: Drift is the gap between a block's timestamp and your own clock or another data source. On Polygon it shows up as the average interval between blocks wandering slightly above or below 2 seconds, so a fixed assumption like "30 blocks = 60 seconds" is only approximate. Measure elapsed time from the timestamps themselves rather than multiplying block counts by an assumed interval.

Working with Timestamps

1// Get block timestamp
2const getBlockTimestamp = async (blockNumber) => {
3  const block = await web3.eth.getBlock(blockNumber);
4  return block.timestamp;
5};
6 
7// Calculate average block time
8const getAverageBlockTime = async (blockCount = 100) => {
9  const latestBlock = await web3.eth.getBlockNumber();
10  const oldBlock = await web3.eth.getBlock(latestBlock - blockCount);
11  const newBlock = await web3.eth.getBlock(latestBlock);
12 
13  return (newBlock.timestamp - oldBlock.timestamp) / blockCount;
14};

Best Practices

• Never rely on exact precision: Because a Bor proposer sets the timestamp and it can shift by seconds, treat block.timestamp as approximate. Do not gate anything valuable on second-level equality or on the exact moment a block was produced on chain 137.
• Account for manipulation: In time-sensitive logic, assume a proposer may move the timestamp a few seconds in their favor and make sure that slack cannot be exploited — never derive randomness from block.timestamp, and keep deadline checks coarse enough that a small shift changes nothing material.
• Prefer block numbers for ordering: Block numbers increase by exactly one and are tamper-proof for sequencing, while timestamps can be nudged. Use block numbers to order events, define waiting periods, or anchor snapshots; reserve timestamps for when you genuinely need human-readable wall-clock time.
• Handle drift in integrations: When reconciling Polygon timestamps with off-chain systems or another chain, compare against your own monotonic clock and tolerate a few seconds of skew. Compute elapsed durations from actual block timestamps over the range rather than assuming a fixed 2-second-per-block rate, which slowly drifts.
• Size safe buffers: Add a margin that comfortably exceeds the plausible manipulation window plus a couple of block times — on Polygon a buffer of roughly 30 seconds or more (well beyond a few ~2s blocks) keeps deadlines, lockups, and unlocks safe from both proposer slack and ordinary drift. Widen the buffer further for high-value or adversarial scenarios.

See also

• eth_getBlockByNumber - Retrieve block information including timestamps
• Working with Blocks - General block handling
• Block Gas Management - Managing gas costs over time