How to Understand Oracle Heartbeat and Deviation Threshold
Conclusion: Check specific data sources on data.chain.link, or read contract parameters in a block explorer. Heartbeat is "the maximum time before a mandatory update," and Deviation Threshold is "the price change percentage that triggers an early update." The two are in an "OR" relationship—whichever condition is met first will trigger an update.
Step 1: Find the Data Source (Feed) Address
What to do: First find the contract address for the oracle data source you want to check.
How to do it:
Open data.chain.link, select the network (e.g., Ethereum Mainnet, Arbitrum, etc.) and the trading pair (e.g., ETH/USD, BTC/USD).
The page will directly display the data source's Answer (current price), Deviation threshold, and Heartbeat.
If you need the contract address, look it up on the "Price Feed Contract Addresses" page at docs.chain.link by network and trading pair.
When you're done: You have obtained the contract address and parameter configuration for the data source.
Step 2: Understand Deviation Threshold – Update When Price Changes
What to do: Find out what price deviation from the last update triggers an on-chain update for this data source.
How to do it:
Chainlink nodes continuously monitor the off-chain real price. When the on-chain price deviates from the real price beyond the set threshold, the node triggers a new round of aggregation and on-chain update.
Different data sources have different deviation thresholds. For example, on Ethereum Mainnet, ETH/USD typically has a deviation threshold of ±0.5%, meaning an update is triggered if the price moves more than 0.5%.
Stablecoins or less volatile assets may have a higher threshold; major assets are usually set lower, often in the 0.1%–0.15% range.
When you're done: You know the deviation threshold for this data source and what it means—the price change required to trigger an update.
Step 3: Understand Heartbeat – Update When Time Elapses
What to do: Find out the maximum time before a mandatory update occurs for this data source.
How to do it:
Heartbeat is the "fallback update mechanism." Even if the price hasn't moved, once the heartbeat interval is exceeded, nodes will force an on-chain update.
Heartbeat intervals vary widely across data sources:
Ethereum Mainnet ETH/USD heartbeat is roughly 3,600 seconds (1 hour).
On Arbitrum, BTC/USD and ETH/USD initially had heartbeats as long as 86,400 seconds (24 hours), later reduced.
Stablecoin/USD pairs often have a longer heartbeat, around 24 hours.
BTC/USD on Polygon has a heartbeat of only 60 seconds.
When you're done: You know the heartbeat interval in seconds for this data source, and that "if the price doesn't move, the latest it will update is this interval."
Key Reminder: Heartbeat and deviation threshold are in an "OR" relationship—update triggers when either condition is met. For example, if ETH/USD has a 1-hour heartbeat and a 0.5% deviation threshold, the system will update either when the price changes more than 0.5% or after 1 hour without an update, whichever comes first.
Step 4: Check Different Networks and Trading Pairs, Compare Parameter Differences
What to do: If the same trading pair has different parameters on different chains, you need to verify each one separately.
How to do it:
Use comparison tables from academic research or official documentation. For example, ETH/USD on BSC has a deviation threshold of ±0.1% and a heartbeat of 60 seconds, while on Zksync it is ±0.5% with an 86,400-second heartbeat.
The heartbeat and deviation settings reflect a trade-off between update cost and price accuracy—shorter heartbeat and lower threshold mean more frequent updates but higher gas costs.
When you're done: For a specific trading pair and specific network, you can accurately state the corresponding heartbeat and deviation threshold.
Prerequisites
Confirm the asset pair you want to check (e.g., ETH/USD) and the network (e.g., Ethereum Mainnet, Arbitrum, etc.). Parameters differ across networks and trading pairs.
Common Failure Scenarios
Confusing heartbeat with deviation threshold: Heartbeat is the "time dimension" lower bound for forced updates; deviation threshold is the "price movement dimension" trigger. These are different update mechanisms.
Applying the same heartbeat to all data sources: The heartbeat for ETH/USD and a stablecoin/USD can differ by over 20 times. If developers set the same freshness check threshold in a contract, some data sources may be considered "expired" while others accept "stale" data.
Ignoring parameter differences across chains: The same BTC/USD pair may have a 3,600-second heartbeat on Ethereum Mainnet but up to 86,400 seconds on Arbitrum. Assuming Arbitrum's heartbeat matches Mainnet would underestimate the risk of outdated prices.
Risk Warnings
Fund Risk: If the deviation threshold is set too high or the heartbeat too long, the oracle price may lag behind the real market during extreme volatility, causing DeFi protocols' liquidation logic to fail—your position could be liquidated when it shouldn't be, or not liquidated when it should, leading to bad debt.
Account Risk: No direct account risk.
Compliance Risk: None.
Confirm you have done it correctly: You can accurately state the deviation threshold (e.g., 0.5%) and heartbeat interval (e.g., 3600 seconds) for the target data source, and you know the two are in an "OR" relationship. If you are developing with the contract that uses this data source, incorporate these parameters as reference values for the validPeriod in price freshness checks, and use different heartbeat thresholds for different data sources to determine staleness.
