Chainlink Data Feeds are the quickest way to connect your smart contracts to the real-world data such as asset prices. One use for data feeds is to retrieve the latest pricing data of an asset in a single call and use that data either on-chain in a smart contract or off-chain in another application of your choice.

If you already have a project started and would like to integrate Chainlink, you can add Chainlink to your existing project by using the @chainlink/contracts NPM package.

See the Data Feeds Contract Addresses page for a list of networks and proxy addresses.

Topics

• Retrieve the latest asset prices
• Components of a data feed
• Reading proxy and aggregator Configurations
• Components of an aggregator
• Updates to proxy and aggregator contracts
• Monitoring data feeds
  • Check the latest answer against reasonable limits
  • Check the timestamp of the latest answer

Retrieve the latest asset prices

Smart contracts often act in real-time on data such as prices of assets. This is especially true in DeFi.

For example, Synthetix uses Data Feeds to determine prices on their derivatives platform. Lending and borrowing platforms like AAVE use Data Feeds to ensure the total value of the collateral.

Data Feeds aggregate many data sources and publish them on-chain using a combination of the Decentralized Data Model and Off-Chain Reporting.

Components of a data feed

Data Feeds are an example of a decentralized oracle network and include the following components:

• Consumer: A consumer is an on-chain or off-chain application that uses Data Feeds. Consumer contracts use the AggregatorV3Interface to call functions on the proxy contract and retrieve information from the aggregator contract. For a complete list of functions available in the AggregatorV3Interface, see the Data Feeds API Reference.
• Proxy contract: Proxy contracts are on-chain proxies that point to the aggregator for a particular data feed. Using proxies enables the underlying aggregator to be upgraded without any service interruption to consuming contracts. Proxy contracts can vary from one data feed to another, but the AggregatorProxy.sol contract on Github is a common example.
• Aggregator contract: An aggregator is a contract that receives periodic data updates from the oracle network. Aggregators store aggregated data on-chain so that consumers can retrieve it and act upon it within the same transaction. For a complete list of functions and variables available on most aggregator contracts, see the Data Feeds API Reference.

To learn how to create a consumer contract that uses an existing data feed, read the Using Data Feeds documentation.

Reading proxy and aggregator configurations

Because the proxy and aggregator contracts are all on-chain, you can see the current configuration by reading the variables through an ABI or using a blockchain explorer for your network. For example, you can see the BTC/USD proxy configuration on the Ethereum network using Etherscan.

If you read the BTC/USD proxy configuration, you can query all of the functions and variables that are publicly accessible for that contract including the aggregator address, latestRoundData() function, latestAnswer variable, owner address, latestTimestamp variable, and several others. To see descriptions for the proxy contract variables and functions, see the source code for your specific data feed on Etherscan.

The proxy contract points to an aggregator. This allows you to retrieve data through the proxy even if the aggregator is upgraded. If you view the aggregator address defined in the proxy configuration, you can see the aggregator and its configuration. For example, see the BTC/USD aggregator contract in Etherscan. This contract includes several variables and functions, including another latestRoundData(). To see descriptions for the aggregator variables and functions, see the source code on GitHub or Etherscan.

You can call the latestRoundData() function directly on the aggregator, but it is a best practice to use the proxy instead so that changes to the aggregator do not affect your application. Similar to the proxy contract, the aggregator contract has a latestAnswer variable, owner address, latestTimestamp variable, and several others.

Components of an aggregator

The aggregator contract has several variables and functions that might be useful for your application. Although aggregator contracts are similar for each data feed, some aggregators have different variables. Use the typeAndVersion() function on the aggregator to identify what type of aggregator it is and what version it is running.

Always check the contract source code and configuration to understand how specific data feeds operate. For example, the aggregator contract for BTC/USD on Arbitrum is different from the aggregators on other networks.

For examples of the contracts that are typically used in aggregator deployments, see the libocr repository on GitHub.

For a complete list of functions and variables available on most aggregator contracts, see the Data Feeds API Reference.

Updates to proxy and aggregator contracts

To accommodate the dynamic nature of off-chain environments, Chainlink Data Feeds are updated from time to time to add new features and capabilities as well as respond to externalities such as token migrations, protocol rebrands, extreme market events, and upstream issues with data or node operations.

These updates include changes to the aggregator configuration or a complete replacement of the aggregator that the proxy uses. If you consume data feeds through the proxy, your applications can continue to operate during these changes.

Proxy and aggregator contracts all have an owner address that has permission to change variables and functions. For example, if you read the BTC/USD proxy contract in Etherscan, you can see the owner address. This address is a multi-signature safe (multisig) that you can also inspect.

If you view the multisig contract in Etherscan using the Read as Proxy feature, you can see the full details of the multisig including the list of addresses that can sign and the number of signers required for the multisig to approve actions on any contracts that it owns.

The multisig-coordinated upgradability of Chainlink Data Feeds involves time-tested processes that balance collusion-resistance with the flexibility required to implement improvements and swiftly react to external conditions. The approach taken to upgradability will continue to evolve over time to meet user requirements.

Monitoring data feeds

When you build applications and protocols that depend on data feeds, include monitoring and safeguards to protect against the negative impact of extreme market events, possible malicious activity on third-party venues or contracts, potential delays, and outages.

Create your own monitoring alerts based on deviations in the answers that data feeds provide. This will notify you when potential issues occur so you can respond to them.

Check the latest answer against reasonable limits

The data feed aggregator includes both minAnswer and maxAnswer values. These variables prevent the aggregator from updating the latestAnswer outside the agreed range of acceptable values, but they do not stop your application from reading the most recent answer.

Configure your application to detect when the reported answer is close to reaching minAnswer or maxAnswer and issue an alert so you can respond to a potential market event. Separately, configure your application to detect and respond to extreme price volatility or prices that are outside of your acceptable limits.

Check the timestamp of the latest answer

Chainlink Price Feeds do not provide streaming data. Rather, the aggregator updates its latestAnswer when the value deviates beyond a specified threshold or when the heartbeat idle time has passed. You can find the heartbeat and deviation values for each data feed at data.chain.link or in the Contract Addresses lists.

Your application should track the latestTimestamp variable or use the updatedAt value from the latestRoundData() function to make sure that the latest answer is recent enough for your application to use it. If your application detects that the reported answer is not updated within the heartbeat or within time limits that you determine are acceptable for your application, pause operation or switch to an alternate operation mode while identifying the cause of the delay.

During periods of low volatility, the heartbeat triggers updates to the latest answer. Some heartbeats are configured to last several hours, so your application should check the timestamp and verify that the latest answer is recent enough for your application.

To learn more about the heartbeat and deviation threshold, read the Decentralized Data Model page.