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 & Receive Data

Suggest Edits

Chainlink can provide your smart contract with access to any external API you want to connect with. Once you have a Chainlinked project, you can then use the methods provided by the Chainlink Library to request external data to be ingested by your smart contract.

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.

Network Information

Use a listing service to find nodes and Job IDs to service your requests.

Requesting data

In order to create requests, you will need to specify parameters for the Chainlink node to use when processing your job. For details on which parameters to specify, see our Adapters page. 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(bytes32 _jobId) public returns (bytes32 requestId) {
  // newRequest takes a JobID, a callback address, and callback function as input
  Chainlink.Request memory req = buildChainlinkRequest(_jobId, address(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 = sendChainlinkRequest(req, 1 * LINK);
}
 
// Creates a Chainlink request with the int256 multiplier job and returns the requestId
function requestEthereumChange(bytes32 _jobId, string _currency) public returns (bytes32 requestId) {
  // newRequest takes a JobID, a callback address, and callback function as input
  Chainlink.Request memory req = buildChainlinkRequest(_jobId, address(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 = sendChainlinkRequest(req, 1 * LINK);
}
 
// Creates a Chainlink request with the uint256 multiplier job and returns the requestId
function requestEthereumPrice(bytes32 _jobId, string _currency) public returns (bytes32 requestId) {
  // newRequest takes a JobID, a callback address, and callback function as input
  Chainlink.Request memory req = buildChainlinkRequest(_jobId, address(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 = sendChainlinkRequest(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/src/v0.4/ChainlinkClient.sol";

// MyContract inherits the ChainlinkClient contract to gain the
// functionality of creating Chainlink requests
contract ChainlinkExample is ChainlinkClient {
  // 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
    setPublicChainlinkToken();
    owner = msg.sender;
  }

  // Creates a Chainlink request with the uint256 multiplier job
  function requestEthereumPrice(address _oracle, bytes32 _jobId, uint256 _payment) 
    public
    onlyOwner
  {
    // newRequest takes a JobID, a callback address, and callback function as input
    Chainlink.Request memory req = buildChainlinkRequest(_jobId, address(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 the amount of payment specified to the oracle
    sendChainlinkRequestTo(_oracle, req, _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;
  }
  
  // cancelRequest allows the owner to cancel an unfulfilled request
  function cancelRequest(
    bytes32 _requestId,
    uint256 _payment,
    bytes4 _callbackFunctionId,
    uint256 _expiration
  )
    public
    onlyOwner
  {
    cancelChainlinkRequest(_requestId, _payment, _callbackFunctionId, _expiration);
  }

  
  // withdrawLink allows the owner to withdraw any extra LINK on the contract
  function withdrawLink()
    public
    onlyOwner
  {
    LinkTokenInterface link = LinkTokenInterface(chainlinkTokenAddress());
    require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
  }
  
  modifier onlyOwner() {
    require(msg.sender == owner);
    _;
  }
}
 
pragma solidity ^0.5.0;

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

// MyContract inherits the ChainlinkClient contract to gain the
// functionality of creating Chainlink requests
contract ChainlinkExample is ChainlinkClient {
  // 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
    setPublicChainlinkToken();
    owner = msg.sender;
  }

  // Creates a Chainlink request with the uint256 multiplier job
  function requestEthereumPrice(address _oracle, bytes32 _jobId, uint256 _payment) 
    public
    onlyOwner
  {
    // newRequest takes a JobID, a callback address, and callback function as input
    Chainlink.Request memory req = buildChainlinkRequest(_jobId, address(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 the amount of payment specified to the oracle
    sendChainlinkRequestTo(_oracle, req, _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;
  }
  
  // cancelRequest allows the owner to cancel an unfulfilled request
  function cancelRequest(
    bytes32 _requestId,
    uint256 _payment,
    bytes4 _callbackFunctionId,
    uint256 _expiration
  )
    public
    onlyOwner
  {
    cancelChainlinkRequest(_requestId, _payment, _callbackFunctionId, _expiration);
  }

  
  // withdrawLink allows the owner to withdraw any extra LINK on the contract
  function withdrawLink()
    public
    onlyOwner
  {
    LinkTokenInterface link = LinkTokenInterface(chainlinkTokenAddress());
    require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
  }
  
  modifier onlyOwner() {
    require(msg.sender == owner);
    _;
  }
}
 
pragma solidity ^0.6.0;

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

// MyContract inherits the ChainlinkClient contract to gain the
// functionality of creating Chainlink requests
contract ChainlinkExample is ChainlinkClient {
  // 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
    setPublicChainlinkToken();
    owner = msg.sender;
  }

  // Creates a Chainlink request with the uint256 multiplier job
  function requestEthereumPrice(address _oracle, bytes32 _jobId, uint256 _payment) 
    public
    onlyOwner
  {
    // newRequest takes a JobID, a callback address, and callback function as input
    Chainlink.Request memory req = buildChainlinkRequest(_jobId, address(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 the amount of payment specified to the oracle
    sendChainlinkRequestTo(_oracle, req, _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;
  }
  
  // cancelRequest allows the owner to cancel an unfulfilled request
  function cancelRequest(
    bytes32 _requestId,
    uint256 _payment,
    bytes4 _callbackFunctionId,
    uint256 _expiration
  )
    public
    onlyOwner
  {
    cancelChainlinkRequest(_requestId, _payment, _callbackFunctionId, _expiration);
  }

  
  // withdrawLink allows the owner to withdraw any extra LINK on the contract
  function withdrawLink()
    public
    onlyOwner
  {
    LinkTokenInterface link = LinkTokenInterface(chainlinkTokenAddress());
    require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
  }
  
  modifier onlyOwner() {
    require(msg.sender == owner);
    _;
  }
}

Updated 3 days ago

What's Next

Solidity Reference

Request & Receive Data

Suggested Edits are limited on API Reference Pages

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