Smart contracts on any blockchain can connect to any API by integrating with Chainlink oracles. We’ve already seen massive growth of API and off-chain data use in Solidity since Chainlink has entered the space as an oracle solution. Now that list is growing rapidly to include Polkadot, Avalanche, Binance Smart Chain, Bitcoin via RSK, and more as all these chains benefit from API access to the external world. Chainlink is well known as the leading framework for DeFi Price Feeds, which currently secures billions in DeFi value. While Chainlink Price Feeds are an important functionality that empowers a multitude of DeFi platforms users know and love, that alone does not revolutionize the capabilities of smart contracts.

Chainlink was designed with a much broader goal in mind: to be the standard data middleware layer for smart contracts and unlock the capability for smart contracts to reliably trigger events in the external world. To accomplish this, Chainlink gives Solidity developers and other smart contract developers a framework for interacting with any external API. This guide shows you exactly how to do so today, live on the Ethereum mainnet.

Quickstart Guide

Here’s a summary of the fastest way to get your smart contract up and running with Chainlink-secured API data, starting with our Make an API GET Request Remix gist.

• Choose your return type:
• Define your return data global variable according to the data you’re requesting, string, uint, etc. “volume” in the example code.
• Update fulfill function assignment.
• Pick your oracle and job:
• Using an oracle listing service such as market.link, find your oracle(s) of choice and update the oracle address and job ID.
• Add API call to request:
• Update request struct to include your desired API command and URL.
• Update path to parse the JSON data to be returned.
• Compile, deploy, and fund:
• In Remix, compile the contract, deploy as injected Web3 to your desired testnet, then send LINK to the contract address so it’s able to pay for requests.

That’s it! In about 15 minutes you can have your own externally aware contract deployed on-chain and making API requests. You can learn more about connecting your smart contract at our Introduction to Using Any API page and continue below for a more in-depth analysis of making an HTTP GET request.

Chainlink Adapters
The first concept to cover is Chainlink Adapters. Adapters are the data manipulation functions that every Chainlink node supports by default. Through these adapters, all developers have a standard interface for making data requests and node operators have a standard for serving that data. These adapters include functionality such as HTTP GET, HTTP POST, Compare, Copy, etc. Adapters are your dApp’s connection to the external world’s data.

For example, here are the parameters for the HttpGet adapter:

• get: takes a string containing the URL to make a GET request to.
• headers: takes an object containing keys as strings and values as arrays of strings.
• queryParams: takes a string or array of strings for the URL’s query parameters.
• extPath: takes a slash-delimited string or array of strings to be appended to the job’s URL.

Chainlink Requests

For your smart contract to interact with these adapters, we need to introduce another element: requests. All contracts that inherit from ChainlinkClient can create a Chainlink.Request struct that allows developers to form a request to a Chainlink node. Submitting this request requires some basic fields such as the address of the node you wish to use as your oracle, the job ID, and the agreed-upon fee. In addition to those default fields, you must add your desired adapter parameters to the request struct like so:

// Set the URL to perform the GET request on
request.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");

In this way, requests are flexible and can be formulated to fit a variety of situations involving getting, posting, and manipulating any API since the requests can contain any of the adapter functions. For more information on the construction of a request and the functions needed to submit it and receive a response within your ChainlinkClient contract, please see our full HTTP GET request example.

Existing Chainlink Job Specs

For certain common requests, a node operator may already have an existing oracle job configured and in this case, the request becomes much simpler. Rather than building a request struct with the necessary adapters, the default request struct is all you need to create. No additional adapter parameters are needed, the oracle you choose will know how to respond based on the jobId provided when creating the request struct.

An example of this is given below, taken from the full CoinGecko API Consumer Example.

Chainlink External Adapters

External adapters are the “whatever data you need, we can handle it” of Chainlink. Since they are pieces of code that exist off-chain with the Chainlink node, they can be written in any language of your choice and perform whatever functionality you can think up so long as the data input and output adhere to the adapter’s JSON specification. These external adapters open up Chainlink requests to perform unique new actions such as connecting a Tesla to a smart contract or authenticating your Reddit account in a smart contract. External adapters act as the interface between the Chainlink node and external data, letting the node operator know how to request and receive the JSON response that is then consumed on-chain. Defining this interface specification off-chain through an external adapter opens up vast possibilities: you can now store your API credentials off-chain in any manner you see fit, data can be manipulated any way you can code up in the language of your choosing, and all this happens without using any gas. In a sense, external adapters are like a layer 2 oracle, packaging up data outside the blockchain with speed and low cost and putting it into one tidy JSON format to be verifiably committed on-chain by the Chainlink node.

External adapters are a large part of what makes Chainlink such versatile oracle middleware. Contract developers are free to implement these adapters as needed or they can choose from existing adapters on the Chainlink Market. If you are a smart contract developer looking to create an external adapter, Chainlink only requires you to specify the JSON interfaces for the data request and the return data. In between those two interfaces is where developers are free to create and manipulate the data to fit their precise use case. As a node operator, in order to support the external adapter and handle the additional requests, you must create a bridge for it in your node UI, add the adapter’s bridge name to your supported tasks, and define a job spec for it.

{
  "initiators": [
    { "type": "runLog" }
  ],
  "tasks": [
    { "type": "randomNumber" },
    { "type": "copy",
      "params": {"copyPath": ["details", "current"]}},
    { "type": "multiply",
      "params": {"times": 100 }},
    { "type": "ethuint256" },
    { "type": "ethtx" }
  ]
}

For a full example of creating an external adapter, please see our External Adapter Developers page.

Chainlink is striving to give blockchain and smart contract developers the tools to empower their smart contracts with real-world data, exactly how they need it. Chainlink’s design incorporates both direct calls to any API through default adapters and extensible external adapters, giving developers a flexible platform to create as they see fit, with any data they might need. If you’re a smart contract developer looking to increase the utility of your smart contract with external data or simply wish to learn more about Chainlink, please check out the resources listed below.

Start Building with Chainlink Today

Want to try Chainlink out? Follow our example walkthrough, and easily deploy your first smart contract that interacts with off-chain data.

If you’re developing a product that could benefit from Chainlink oracles or would like to assist in the open-source development of the Chainlink Network, visit the developer documentation or join the technical discussion on Discord.