Chainlink Developers

Welcome to the Chainlink documentation site. You'll find comprehensive guides and documentation to help you start working with Chainlink as quickly as possible, as well as support if you get stuck. Click here for an introductory walkthrough on how to create a Chainlink request on the Ropsten test network!

Building on Chainlink? Click here to get started!

Get Started

Using Chainlink Reference Data Contracts

Chainlink reference data contracts are on-chain reference points for external data that can be widely relied on across a smart contract network. These contracts are updated on a regular basis by multiple Chainlink nodes. This page will teach you how to make use of them.

Import Chainlink into Your Project

In order to make it easy to use the reference data contracts, you can import @Chainlink Contracts NPM package into your Solidity project.

npm install @chainlink/contracts --save
yarn add chainlink

Also see Create a Chainlinked Project for additional ways to use Chainlink contracts in your project.

Inherit the AggregatorInterface in Your Contract

Import the AggregatorInterface.sol contract into the source of the contract you want to consume reference data.

import "@chainlink/contracts/src/v0.4/interfaces/AggregatorInterface.sol";
import "@chainlink/contracts/src/v0.5/dev/AggregatorInterface.sol";
import "@chainlink/contracts/src/v0.6/dev/AggregatorInterface.sol";

Specify the Address of the Reference Contract

Set the address of the reference contract that contains the reference data you wish to consume.

AggregatorInterface internal ref;

function setReferenceContract(address _aggregator)
  public
  onlyOwner()
{
  ref = AggregatorInterface(_aggregator);
}
AggregatorInterface internal ref;

constructor(address _aggregator) public {
  ref = AggregatorInterface(_aggregator);
}

Use the Reference Data

These docs have been updated to the latest AggregatorInterface. currentAnswer has been renamed to latestAnswer, updatedHeight has been renamed to latestTimestamp and returns the block timestamp instead of the block number.

Now that your contract is pointing towards a reference contract, you're ready to consume the data.

function getLatestPrice() public view returns (int256) {
  return ref.latestAnswer();
}

You can also check the block timestamp at which the reference data was last updated.

function getLatestTimestamp() public view returns (uint256) {
  return ref.latestTimestamp();
}

To get historical data, call latestRound then you can provide getAnswer and getTimestamp with that roundId to obtain the value at that round, or a decremented value.

function getPreviousAnswer(uint256 _back) public view returns (int256) {
  uint256 latest = ref.latestRound();
  require(_back <= latest, "Not enough history");
  return ref.getAnswer(latest - _back);
}

function getPreviousTimestamp(uint256 _back) public view returns (uint256) {
  uint256 latest = ref.latestRound();
  require(_back <= latest, "Not enough history");
  return ref.getTimestamp(latest - _back);
}

Complete Example

Below is a brief but complete example of a consuming contract of Chainlink reference data.

pragma solidity ^0.4.24;

import "@chainlink/contracts/src/v0.4/interfaces/AggregatorInterface.sol";

contract ReferenceConsumer {
  AggregatorInterface internal ref;

  constructor(address _aggregator) public {
    ref = AggregatorInterface(_aggregator);
  }

  function getLatestAnswer() public view returns (int256) {
    return ref.latestAnswer();
  }

  function getLatestTimestamp() public view returns (uint256) {
    return ref.latestTimestamp();
  }

  function getPreviousAnswer(uint256 _back) public view returns (int256) {
    uint256 latest = ref.latestRound();
    require(_back <= latest, "Not enough history");
    return ref.getAnswer(latest - _back);
  }

  function getPreviousTimestamp(uint256 _back) public view returns (uint256) {
    uint256 latest = ref.latestRound();
    require(_back <= latest, "Not enough history");
    return ref.getTimestamp(latest - _back);
  }
}
pragma solidity ^0.5.0;

import "@chainlink/contracts/src/v0.5/dev/AggregatorInterface.sol";

contract ReferenceConsumer {
  AggregatorInterface internal ref;

  constructor(address _aggregator) public {
    ref = AggregatorInterface(_aggregator);
  }

  function getLatestAnswer() public view returns (int256) {
    return ref.latestAnswer();
  }

  function getLatestTimestamp() public view returns (uint256) {
    return ref.latestTimestamp();
  }

  function getPreviousAnswer(uint256 _back) public view returns (int256) {
    uint256 latest = ref.latestRound();
    require(_back <= latest, "Not enough history");
    return ref.getAnswer(latest - _back);
  }

  function getPreviousTimestamp(uint256 _back) public view returns (uint256) {
    uint256 latest = ref.latestRound();
    require(_back <= latest, "Not enough history");
    return ref.getTimestamp(latest - _back);
  }
}
pragma solidity ^0.6.0;

import "@chainlink/contracts/src/v0.6/dev/AggregatorInterface.sol";

contract ReferenceConsumer {
  AggregatorInterface internal ref;

  constructor(address _aggregator) public {
    ref = AggregatorInterface(_aggregator);
  }

  function getLatestAnswer() public view returns (int256) {
    return ref.latestAnswer();
  }

  function getLatestTimestamp() public view returns (uint256) {
    return ref.latestTimestamp();
  }

  function getPreviousAnswer(uint256 _back) public view returns (int256) {
    uint256 latest = ref.latestRound();
    require(_back <= latest, "Not enough history");
    return ref.getAnswer(latest - _back);
  }

  function getPreviousTimestamp(uint256 _back) public view returns (uint256) {
    uint256 latest = ref.latestRound();
    require(_back <= latest, "Not enough history");
    return ref.getTimestamp(latest - _back);
  }
}

Live Reference Data Contracts (Ethereum Mainnet)

The latestAnswer value for all USD reference data contracts is multiplied by 100000000 before being written on-chain and by 1000000000000000000 for all ETH pairs.

To view the addresses of data feeds deployed to the Ethereum main network, visit our Feeds page.

Test Reference Data Contracts (Ropsten)

Below are the available reference data contracts on the Ropsten test network.

Pair
Address

sCEX/USD (Exchange index)

sDEFI/USD (Exchange index)

Test Reference Data Contracts (Rinkeby)

Below are the available reference data contracts on the Rinkeby test network.

Test Reference Data Contracts (Kovan)

Below are the available reference data contracts on the Kovan test network.

sCEX/USD (Exchange index)

sDEFI/USD (Exchange index)

Updated 3 days ago

Using Chainlink Reference Data Contracts


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.