Chainlink

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

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!

Creating a new Chainlinked project

Using Truffle, it's very easy to get started creating Chainlinked contracts from a template. Simply run the command below to unbox a Chainlinked contract in your current directory.

truffle unbox smartcontractkit/chainlinked

Add Chainlink to your existing project

If you already have a project started, you can add Chainlink to it by running one of the following commands.

With NPM:

npm install chainlink --save

With Yarn:

yarn add 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. Our contracts are written for the 0.4.24 Solidity compiler version.

pragma solidity ^0.4.24;

import "chainlink/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests.
contract MyContract is Chainlinked {
  constructor() public {
    // Set the address for the LINK token for the network.
    setLinkToken(0x20fE562d797A42Dcb3399062AE9546cd06f63280);
    // Set the address of the oracle to create requests to.
    setOracle(0xc99B3D447826532722E41bc36e644ba3479E4365);
  }
  // Additional functions here:
  
}
 
pragma solidity ^0.4.24;

import "chainlink/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests.
contract MyContract is Chainlinked {
  constructor() public {
    // Set the address for the LINK token for the network.
    setLinkToken(0x01BE23585060835E02B77ef475b0Cc51aA1e0709);
    // Set the address of the oracle to create requests to.
    setOracle(0x7AFe1118Ea78C1eae84ca8feE5C65Bc76CcF879e);
  }
  // Additional functions here:
  
}
 
pragma solidity ^0.4.24;

import "chainlink/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests.
contract MyContract is Chainlinked {
  constructor() public {
    // Set the address for the LINK token for the network.
    setLinkToken(0xa36085F69e2889c224210F603D836748e7dC0088);
    // Set the address of the oracle to create requests to.
    setOracle(0x2f90A6D021db21e1B2A077c5a37B3C7E75D15b7e);
  }
  // Additional functions here:
  
}
 
pragma solidity ^0.4.24;

import "chainlink/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests.
contract MyContract is Chainlinked {
  constructor(address _link, address _oracle) public {
    // Set the address for the LINK token for the network.
    setLinkToken(_link);
    // Set the address of the oracle to create requests to.
    setOracle(_oracle);
  }
  // Additional functions here:
  
}

It's a good idea to set the address for the LINK token and oracle contract addresses in your constructor. You may also set them dynamically as input parameters.

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.

// Creates constants for the JobIDs within the documentation. 
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");
 
// Creates constants for the JobIDs within the documentation.
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");
 
// Creates constants for the JobIDs within the documentation.
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.

// Creates a Chainlink request with the bytes32 job and returns the requestId
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);
  // Adds a URL with the key "get" to the request parameters
  req.add("get", "https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD");
  // Adds a dot-delimited JSON path with the key "path" to the request parameters
  req.add("path", "RAW.ETH.USD.LASTMARKET");
  // Sends the request with 1 LINK to the oracle contract
  requestId = chainlinkRequest(req, 1 * LINK);
  }
 
// Creates a Chainlink request with the int256 multiplier job and returns the requestId
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);
  // Adds a URL with the key "get" to the request parameters
  req.add("get", "https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD,EUR,JPY");
  // Create an array to dynamically set specific keys of the JSON path in request parameters
  string[] memory path = new string[](4);
  path[0] = "RAW";
  path[1] = "ETH";
  path[2] = _currency;
  path[3] = "CHANGEPCTDAY";
  // Adds the array of strings with the key "path" to the request parameters
  req.addStringArray("path", path);
  // Adds an integer with the key "times" to the request parameters
  req.addInt("times", 1000000000);
  // Sends the request with 1 LINK to the oracle contract
  requestId = chainlinkRequest(req, 1 * LINK);
}
 
// Creates a Chainlink request with the uint256 multiplier job and returns the requestId
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);
  // Adds a URL with the key "get" to the request parameters
  req.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD,EUR,JPY");
  // Uses input param (dot-delimited string) as the "path" in the request parameters
  req.add("path", _currency);
  // Adds an integer with the key "times" to the request parameters
  req.addInt("times", 100);
  // Sends the request with 1 LINK to the oracle contract
  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. Chainlink fulfillment methods expect a requestId to be returned as the first parameter as bytes32, and the second parameter to be the type specified in the JobID that was used for the request. Chainlinked contracts can currently only consume a single EVM word of data per request.

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

bytes32 public market;

// fulfillEthereumLastMarket receives a bytes32 data type
function fulfillEthereumLastMarket(bytes32 _requestId, bytes32 _market)
  // Use recordChainlinkFulfillment to ensure only the requesting oracle can fulfill
  public recordChainlinkFulfillment(_requestId)
{
  market = _market;
}
 
int256 public change;

// fulfillEthereumChange receives a int256 data type
function fulfillEthereumChange(bytes32 _requestId, int256 _change)
  // Use recordChainlinkFulfillment to ensure only the requesting oracle can fulfill
  public recordChainlinkFulfillment(_requestId)
{
  change = _change;
}
 
uint256 public price;

// fulfillEthereumPrice receives a uint256 data type
function fulfillEthereumPrice(bytes32 _requestId, uint256 _price)
  // Use recordChainlinkFulfillment to ensure only the requesting oracle can fulfill
  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/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests
contract ChainlinkExample is Chainlinked {
  // Helper constant for testnets: 1 request = 1 LINK
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  // Helper constant for the Chainlink uint256 multiplier JobID
  bytes32 constant UINT256_MUL_JOB = bytes32("493610cff14346f786f88ed791ab7704");

  // Stores the answer from the Chainlink oracle
  uint256 public currentPrice;
  address public owner;

  constructor() public {
    // Set the address for the LINK token for the network
    setLinkToken(0x20fE562d797A42Dcb3399062AE9546cd06f63280);
    // Set the address of the oracle to create requests to
    setOracle(0xc99B3D447826532722E41bc36e644ba3479E4365);
    owner = msg.sender;
  }

  // Creates a Chainlink request with the uint256 multiplier job
  function requestEthereumPrice() 
    public
    onlyOwner
  {
    // newRequest takes a JobID, a callback address, and callback function as input
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    // Adds a URL with the key "get" to the request parameters
    req.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    // Uses input param (dot-delimited string) as the "path" in the request parameters
    req.add("path", "USD");
    // Adds an integer with the key "times" to the request parameters
    req.addInt("times", 100);
    // Sends the request with 1 LINK to the oracle contract
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

  // fulfill receives a uint256 data type
  function fulfill(bytes32 _requestId, uint256 _price)
    public
    // Use recordChainlinkFulfillment to ensure only the requesting oracle can fulfill
    recordChainlinkFulfillment(_requestId)
  {
    currentPrice = _price;
  }
  
  // withdrawLink allows the owner to withdraw any extra LINK on the contract
  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/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests
contract ChainlinkExample is Chainlinked {
  // Helper constant for testnets: 1 request = 1 LINK
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  // Helper constant for the Chainlink uint256 multiplier JobID
  bytes32 constant UINT256_MUL_JOB = bytes32("6d1bfe27e7034b1d87b5270556b17277");

  // Stores the answer from the Chainlink oracle
  uint256 public currentPrice;
  address public owner;

  constructor() public {
    // Set the address for the LINK token for the network
    setLinkToken(0x01BE23585060835E02B77ef475b0Cc51aA1e0709);
    // Set the address of the oracle to create requests to
    setOracle(0x7AFe1118Ea78C1eae84ca8feE5C65Bc76CcF879e);
    owner = msg.sender;
  }

  // Creates a Chainlink request with the uint256 multiplier job
  function requestEthereumPrice() 
    public
    onlyOwner
  {
    // newRequest takes a JobID, a callback address, and callback function as input
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    // Adds a URL with the key "get" to the request parameters
    req.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    // Uses input param (dot-delimited string) as the "path" in the request parameters
    req.add("path", "USD");
    // Adds an integer with the key "times" to the request parameters
    req.addInt("times", 100);
    // Sends the request with 1 LINK to the oracle contract
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

  // fulfill receives a uint256 data type
  function fulfill(bytes32 _requestId, uint256 _price)
    public
    // Use recordChainlinkFulfillment to ensure only the requesting oracle can fulfill
    recordChainlinkFulfillment(_requestId)
  {
    currentPrice = _price;
  }
  
  // withdrawLink allows the owner to withdraw any extra LINK on the contract
  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/contracts/Chainlinked.sol";

// MyContract inherits the Chainlinked contract to gain the
// functionality of creating Chainlink requests
contract ChainlinkExample is Chainlinked {
  // Helper constant for testnets: 1 request = 1 LINK
  uint256 constant private ORACLE_PAYMENT = 1 * LINK;
  // Helper constant for the Chainlink uint256 multiplier JobID
  bytes32 constant UINT256_MUL_JOB = bytes32("29fa9aa13bf1468788b7cc4a500a45b8");

  // Stores the answer from the Chainlink oracle
  uint256 public currentPrice;
  address public owner;

  constructor() public {
    // Set the address for the LINK token for the network
    setLinkToken(0xa36085F69e2889c224210F603D836748e7dC0088);
    // Set the address of the oracle to create requests to
    setOracle(0x2f90A6D021db21e1B2A077c5a37B3C7E75D15b7e);
    owner = msg.sender;
  }

  // Creates a Chainlink request with the uint256 multiplier job
  function requestEthereumPrice() 
    public
    onlyOwner
  {
    // newRequest takes a JobID, a callback address, and callback function as input
    Chainlink.Request memory req = newRequest(UINT256_MUL_JOB, this, this.fulfill.selector);
    // Adds a URL with the key "get" to the request parameters
    req.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
    // Uses input param (dot-delimited string) as the "path" in the request parameters
    req.add("path", "USD");
    // Adds an integer with the key "times" to the request parameters
    req.addInt("times", 100);
    // Sends the request with 1 LINK to the oracle contract
    chainlinkRequest(req, ORACLE_PAYMENT);
  }

  // fulfill receives a uint256 data type
  function fulfill(bytes32 _requestId, uint256 _price)
    public
    // Use recordChainlinkFulfillment to ensure only the requesting oracle can fulfill
    recordChainlinkFulfillment(_requestId)
  {
    currentPrice = _price;
  }
  
  // withdrawLink allows the owner to withdraw any extra LINK on the contract
  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);
    _;
  }
}

What's Next

Chainlinks (Testnet)
Addresses and Job Specs
Chainlinked Helpers and Functions

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.

Suggested Edits are limited on API Reference Pages

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