Request data using Chainlink

Chainlink will provide your smart contract with access to any external API you want to connect your smart contract with. You can begin by trying a Chainlink out on an Ethereum testnet.

Suggest Edits

Developers wanting to add external data to their contracts will need to import the Chainlinked contract into their project. The Chainlinked contract contains helper methods in order to simplify the process of making a Chainlink request on-chain for external data.

Requirements

Your contract will need to be funded with LINK in order to create a request. On the test networks, we simplify the amount to 1 LINK = 1 request. To obtain testnet LINK, visit the faucets below:
You will need a Job ID that's associated with the type of data you want. View the Addresses and Job IDs page for information specific to your network.

If you have any questions, feel free to ask us on Gitter!

Add Chainlink to your project

Start off by adding Chainlink to your project which is hosted on GitHub.

With NPM:

$ npm install github:smartcontractkit/chainlink --save

With Yarn:

$ yarn add github:smartcontractkit/chainlink

If you are using ZeppelinOS, you can link it to your project by running:

$ zos link chainlink

Create your Chainlinked contract

Import Chainlinked.sol into your contract so you can inherit the Chainlinked behavior.

pragma solidity ^0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract MyContract is Chainlinked {
  constructor() public {
    setLinkToken(0x20fE562d797A42Dcb3399062AE9546cd06f63280);
    setOracle(0xc99B3D447826532722E41bc36e644ba3479E4365);
  }
  // Additional functions here:
  
}

pragma solidity ^0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract MyContract is Chainlinked {
  constructor() public {
    setLinkToken(0x01BE23585060835E02B77ef475b0Cc51aA1e0709);
    setOracle(0x7AFe1118Ea78C1eae84ca8feE5C65Bc76CcF879e);
  }
  // Additional functions here:
  
}

pragma solidity ^0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract MyContract is Chainlinked {
  constructor() public {
    setLinkToken(0xa36085F69e2889c224210F603D836748e7dC0088);
    setOracle(0x2f90A6D021db21e1B2A077c5a37B3C7E75D15b7e);
  }
  // Additional functions here:
  
}

A complete Chainlinked example contract is available at the bottom of this page.

Requesting data

When a request is created on-chain from your smart contract for the available Job IDs (helpers below), you will need to specify parameters about the data you want Chainlink to retrieve. For details on which parameters to specify, see our Adapters page.

bytes32 constant GET_BYTES32_JOB = bytes32("5b280bfed77646d297fdb6e718c7127a");
bytes32 constant POST_BYTES32_JOB = bytes32("469e74c5bca740c0addba9ea67eecc51");
bytes32 constant INT256_JOB = bytes32("93032b68d4704fa6be2c3ccf7a23c107");
bytes32 constant INT256_MUL_JOB = bytes32("e055293deb37425ba83a2d5870c57649");
bytes32 constant UINT256_JOB = bytes32("fb5fb7b18921487fb26503cb075abf41");
bytes32 constant UINT256_MUL_JOB = bytes32("493610cff14346f786f88ed791ab7704");
bytes32 constant BOOL_JOB = bytes32("7ac0b3beac2c448cb2f6b2840d61d31f");

bytes32 constant GET_BYTES32_JOB = bytes32("b0bde308282843d49a3a8d2dd2464af1");
bytes32 constant POST_BYTES32_JOB = bytes32("c28c092ad6f045c79bdbd54ebb42ce4d");
bytes32 constant INT256_JOB = bytes32("648f1b4629324c7ab41b7980b3091138");
bytes32 constant INT256_MUL_JOB = bytes32("c8084988f0b54520ba17945c4a2ab7bc");
bytes32 constant UINT256_JOB = bytes32("367c3cb39ab34bccad27deea5e37f365");
bytes32 constant UINT256_MUL_JOB = bytes32("6d1bfe27e7034b1d87b5270556b17277");
bytes32 constant BOOL_JOB = bytes32("4ce9b71a1ac94abcad1ff9198e760b8c");

bytes32 constant GET_BYTES32_JOB = bytes32("50fc4215f89443d185b061e5d7af9490");
bytes32 constant POST_BYTES32_JOB = bytes32("b9fd06bb42dd444db1b944849cbffb11");
bytes32 constant INT256_JOB = bytes32("f9d13102fb90482f992fc06e15ed373b");
bytes32 constant INT256_MUL_JOB = bytes32("ad752d90098243f8a5c91059d3e5616c");
bytes32 constant UINT256_JOB = bytes32("2c6578f488c843588954be403aba2deb");
bytes32 constant UINT256_MUL_JOB = bytes32("29fa9aa13bf1468788b7cc4a500a45b8");
bytes32 constant BOOL_JOB = bytes32("6d914edc36e14d6c880c9c55bda5bc04");

Specifying parameters is accomplished by using methods within Chainlink.Request which takes a key (as a string) and value. We have the following method available for different value types:

add: Adds a string
addBytes: Adds bytes
addInt: Adds a int256
addUint: Adds a uint256
addStringArray: Adds an array of strings

In the examples below, we specify a "get" key for the HttpGet adapter, a "path" key for the JsonParse adapter, and a "times" key for the Multiply adapter.

function requestEthereumLastMarket() public returns (bytes32 requestId) {
  // newRequest takes a JobID, a callback address, and callback function as input
  Chainlink.Request memory req = newRequest(GET_BYTES32_JOB, this, this.fulfillEthereumLastMarket.selector);
  req.add("get", "https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD");
  req.add("path", "RAW.ETH.USD.LASTMARKET");
  requestId = chainlinkRequest(req, 1 * LINK);
  }

function requestEthereumChange(string _currency) public returns (bytes32 requestId) {
  // newRequest takes a JobID, a callback address, and callback function as input
  Chainlink.Request memory req = newRequest(INT256_MUL_JOB, this, this.fulfillEthereumChange.selector);
  req.add("get", "https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD,EUR,JPY");
  string[] memory path = new string[](4);
  path[0] = "RAW";
  path[1] = "ETH";
  path[2] = _currency;
  path[3] = "CHANGEPCTDAY";
  req.addStringArray("path", path);
  req.addInt("times", 1000000000);
  requestId = chainlinkRequest(req, 1 * LINK);
}

function requestEthereumPrice(string _currency) public returns (bytes32 requestId) {
  // newRequest takes a JobID, a callback address, and callback function as input
  Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfillEthereumPrice.selector);
  req.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD,EUR,JPY");
  req.add("path", _currency);
  req.addInt("times", 100);
  requestId = chainlinkRequest(req, 1 * LINK);
}

Receiving data

The request examples above each specify a callback function to be triggered when the Chainlink network responds with an answer.

Below are examples of how your contract can receive the data from the Chainlink network:

bytes32 public market;

function fulfillEthereumLastMarket(bytes32 _requestId, bytes32 _market)
  public recordChainlinkFulfillment(_requestId)
{
  market = _market;
}

int256 public change;

function fulfillEthereumChange(bytes32 _requestId, int256 _change)
  public recordChainlinkFulfillment(_requestId)
{
  change = _change;
}

uint256 public price;

function fulfillEthereumPrice(bytes32 _requestId, uint256 _price)
  public recordChainlinkFulfillment(_requestId)
{
  price = _price;
}

Be sure to add the recordChainlinkFulfillment modifier to your fulfillment method to ensure that only Chainlink can call this method. This modifier is included with the Chainlinked contract.

With your Chainlinked contract written, you're now ready to deploy!

Complete Chainlink Contract Example

Below is a complete example contract which can create requests to the Chainlink network and receive answers.

pragma solidity 0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract ChainlinkExample is Chainlinked, Ownable {
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  bytes32 constant UINT256_MUL_JOB = bytes32("493610cff14346f786f88ed791ab7704");

uint256 public currentPrice;
  address public owner;

constructor() public {
    setLinkToken(0x20fE562d797A42Dcb3399062AE9546cd06f63280);
    setOracle(0xc99B3D447826532722E41bc36e644ba3479E4365);
    owner = msg.sender;
  }

function requestEthereumPrice() 
    public
    onlyOwner
  {
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    req.add("url", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    req.add("path", "USD");
    req.addInt("times", 100);
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

pragma solidity 0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract ChainlinkExample is Chainlinked, Ownable {
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  bytes32 constant UINT256_MUL_JOB = bytes32("493610cff14346f786f88ed791ab7704");

  uint256 public currentPrice;
  address public owner;

  constructor() public {
    setLinkToken(0x20fE562d797A42Dcb3399062AE9546cd06f63280);
    setOracle(0xc99B3D447826532722E41bc36e644ba3479E4365);
    owner = msg.sender;
  }

  function requestEthereumPrice() 
    public
    onlyOwner
  {
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    req.add("url", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    req.add("path", "USD");
    req.addInt("times", 100);
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

  function fulfill(bytes32 _requestId, uint256 _price)
    public
    recordChainlinkFulfillment(_requestId)
  {
    currentPrice = _price;
  }
  
  function withdrawLink()
    public
    onlyOwner
  {
    LinkTokenInterface link = LinkTokenInterface(chainlinkToken());
    require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
  }
  
  modifier onlyOwner() {
    require(msg.sender == owner);
    _;
  }
}

pragma solidity 0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract ChainlinkExample is Chainlinked, Ownable {
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  bytes32 constant UINT256_MUL_JOB = bytes32("6d1bfe27e7034b1d87b5270556b17277");

uint256 public currentPrice;
  address public owner;

constructor() public {
    setLinkToken(0x01BE23585060835E02B77ef475b0Cc51aA1e0709);
    setOracle(0x7AFe1118Ea78C1eae84ca8feE5C65Bc76CcF879e);
    owner = msg.sender;
  }

pragma solidity 0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract ChainlinkExample is Chainlinked, Ownable {
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  bytes32 constant UINT256_MUL_JOB = bytes32("6d1bfe27e7034b1d87b5270556b17277");

  uint256 public currentPrice;
  address public owner;

  constructor() public {
    setLinkToken(0x01BE23585060835E02B77ef475b0Cc51aA1e0709);
    setOracle(0x7AFe1118Ea78C1eae84ca8feE5C65Bc76CcF879e);
    owner = msg.sender;
  }

  function requestEthereumPrice() 
    public
    onlyOwner
  {
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    req.add("url", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    req.add("path", "USD");
    req.addInt("times", 100);
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

  function fulfill(bytes32 _requestId, uint256 _price)
    public
    recordChainlinkFulfillment(_requestId)
  {
    currentPrice = _price;
  }
  
  function withdrawLink()
    public
    onlyOwner
  {
    LinkTokenInterface link = LinkTokenInterface(chainlinkToken());
    require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
  }
  
  modifier onlyOwner() {
    require(msg.sender == owner);
    _;
  }
}

pragma solidity 0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract ChainlinkExample is Chainlinked, Ownable {
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  bytes32 constant UINT256_MUL_JOB = bytes32("29fa9aa13bf1468788b7cc4a500a45b8");

uint256 public currentPrice;
  address public owner;

constructor() public {
    setLinkToken(0xa36085F69e2889c224210F603D836748e7dC0088);
    setOracle(0x2f90A6D021db21e1B2A077c5a37B3C7E75D15b7e);
    owner = msg.sender;
  }

pragma solidity 0.4.24;

import "chainlink/solidity/contracts/Chainlinked.sol";

contract ChainlinkExample is Chainlinked, Ownable {
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  bytes32 constant UINT256_MUL_JOB = bytes32("29fa9aa13bf1468788b7cc4a500a45b8");

  uint256 public currentPrice;
  address public owner;

  constructor() public {
    setLinkToken(0xa36085F69e2889c224210F603D836748e7dC0088);
    setOracle(0x2f90A6D021db21e1B2A077c5a37B3C7E75D15b7e);
    owner = msg.sender;
  }

  function requestEthereumPrice() 
    public
    onlyOwner
  {
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    req.add("url", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    req.add("path", "USD");
    req.addInt("times", 100);
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

  function fulfill(bytes32 _requestId, uint256 _price)
    public
    recordChainlinkFulfillment(_requestId)
  {
    currentPrice = _price;
  }
  
  function withdrawLink()
    public
    onlyOwner
  {
    LinkTokenInterface link = LinkTokenInterface(chainlinkToken());
    require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
  }
  
  modifier onlyOwner() {
    require(msg.sender == owner);
    _;
  }
}