How to request data from a REST API to a Solidity Smart Contract

by Vansh Wassan, Integrations Engineer & Developer Relations @ API3

Twitter: @WassanVansh Github: vanshwassan

Part I: Deploy an Airnode to a REST API

As we all know that it is not possible by a Smart Contract to directly access external APIs outside of a blockchain. Interacting with off-chain data while working with Smart Contracts is a real problem for a lot of dApps.

The Ethereum blockchain was designed to be entirely deterministic while the Internet was not. Calling an API directly sounds easy but on a blockchain, it would require all the nodes to call the same endpoint at the same time and expect to get the same data in order to come to a consensus. Plus, the core concept of a blockchain is its security, that is derived from a decentralized network of independent validators that purposefully limit their connection to the outside world.

However, with API3, you can have first-party oracles that are directly operated by the API Providers, called Airnodes that provides data to any on-chain dApp*.* As a result, you can easily make any REST API accessible to a Smart Contract.

---

Say Hello to ChainAPI

ChainAPI is a platform that enables you to integrate and deploy the open-source Airnode with its step-by-step integration and deployment tools.

To get started, go to ChainAPI ChainAPI and log in by connecting your MetaMask.

You will be prompted to confirm and sign the transaction through your MetaMask extension.

Make sure you’re using a new MetaMask Wallet with a fresh mnemonic. Your mnemonic will later be used to deploy the Airnode. You need to keep it extremely safe as this will serve as the “private key” of your deployed Airnode.

Each time you return to ChainAPI you will connect again, using MetaMask, to identify yourself by signing a message for the same account.

Complete the signup process and name your workspace.

Workspaces provides you with a way to invite other users to help or collaborate with integrations and deployments. This makes it easy to manage your Airnode’s as a team or to outsource the process while still maintaining control over your integrations and deployments.

To change the name of your in the future, click on name on the top-left of the dashboard

Within ChainAPI you will be able to create and manage your integrations or Airnode deployments by navigating to the “Integrations” or “Deploy” dashboards on the left hand navigation panel.

---

Integrating your Airnode

For this tutorial, I am going to use dxFeed’s public REST API endpoints to retrieve stock data.

To get started select the “Integrate API” option in the top right hand of the dashboard.

Enter the details about the API that you are integrating.

You need to enter the base URL of your API along with all the endpoints that you want to integrate. As it’s a public API, it doesn’t have any security schemes.

You can now start by adding all your endpoints.

Here, the dxFeed REST API has one GET endpoint /events.json with some query parameters. You can add all the parameters that your API requires.

Now you need to add all the parameters and define where they go (query/header/path/cookie). Here, all the parameters are query params and are required to be defined by the user.

I’ve made the format param fixed as I want it to return the response in json.

Reserved parameters define what part of the response is to be picked and encoded before fulfillment. It can be defined by the requester but we can also hardcode it in the Airnode configuration.

After adding all the required endpoints, you can now press finish and get ready to deploy your Airnode.

---

Deploying your Airnode

To deploy the Airnode, go to the deploy section on the menu. Name your deployment and select the integration that you want to use with it.

Select your Cloud Provider where you want your Airnode to be deployed.

Now select the Chains for your deployment. You can also select multiple networks and providers if you want it on multiple Chains.

Here, we are going to have our Airnode on the Polygon Mumbai Testnet.

Review your configuration for one final time. If everything seems correct, click on next.

Download all the Airnode configuration files and extract them.

This is how your Airnode config directory should look like:

config contains config.json and secrets.env.

• The config.json file is used during the deployment/redeployment of an Airnode to configure its behavior and to provide mappings of API operations.

• The secrets.env file holds values for config.json that must be kept secret.

  
  

The output directory will have the receipt.json that will be generated after you successfully deploy the Airnode.

The aws.env file holds AWS credentials for deployments targeted to AWS.

As we are using AWS as our cloud provider, we need to add our AWS IAM Access Keys with Administrator Access policy. You can refer to this video if you are not sure how to obtain them.

The README.md contains all the steps to deploy the airnode provided in a markdown format.

Open aws.env and add your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY that you just created.

Open config/secrets.env and add your wallet mnemonic. Make sure you keep it extremely safe as this will serve as the “private key” of your deployed Airnode. From the mnemonic phrase, Airnode is able to assign wallet addresses to both the Airnode instance and its users.

You also need to add your Blockchain Provider URL. Here, we are going to use Alchemy for a free Polygon Mumbai Testnet Provider URL. You can use any blockchain provider that supports your network
You can also set-up your *HttpGateway *credentials. It’s an optional service that allows authenticated users to make HTTP requests to your deployed Airnode instance for testing. ChainAPI has already generated these keys for you but you can change them if you want.

One final step before deploying your Airnode is to set Authorizers in the config.json file.

When an Airnode receives a request, it can use on-chain authorizer contracts to verify if a response is warranted. This allows the Airnode to implement a wide variety of policies and to authorize requester contract access to its underlying API.

For the scope of this tutorial, we can set the authorizer array empty in config.json so that any requester contract can access the Airnode

Now you are ready to deploy your Airnode. Make sure you have Docker installed on your system.

Copy and paste the commands below to your terminal at the root directory of your deployment package.

Windows

docker run -it --rm ^
      --env-file aws.env ^
      -v "%cd%/config:/app/config" ^
      -v "%cd%/output:/app/output" ^
      api3/airnode-deployer:0.7.3 deploy

OSX

docker run -it --rm \
      --env-file aws.env \
      -e USER_ID=$(id -u) -e GROUP_ID=$(id -g) \
      -v "$(pwd)/config:/app/config" \
      -v "$(pwd)/output:/app/output" \
      api3/airnode-deployer:0.7.3 deploy

Linux

docker run -it --rm \
      --env-file aws.env \
      -e USER_ID=$(id -u) -e GROUP_ID=$(id -g) \
      -v "$(pwd)/config:/app/config" \
      -v "$(pwd)/output:/app/output" \
      api3/airnode-deployer:0.7.3 deploy

Your Airnode is now deployed. You can check its status on the deployment section.

Check out the Github Repo for this guide here.

Part II: How to code a Requester contract to call and read the data from the Airnode.

In Part I, we successfully integrated and deployed an Airnode through ChainAPI. Now we will code a simple Requester Contract to call and read data from our Airnode.

Before starting, make sure you set up the Airnode Monorepo on your system. Follow through the Readme to install and build all the dependencies and packages to be able to access the Airnode CLI.

Clone the Airnode Monorepo.

$ git clone https://github.com/api3dao/airnode.git .

To install the dependencies,

$ yarn run bootstrap

To build all the packages,

$ yarn run build

An Airnode is a first-party oracle that pushes off-chain API data to your on-chain contract. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester.

<https://docs.api3.org/airnode/v0.8/grp-developers/ ](https://docs.api3.org/airnode/v0.8/grp-developers/)

A *Requester *is a contract that triggers an Airnode request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet.

The Requester then calls the protocol contract, which emits a blockchain event with the request parameters. Airnode listens to the events emitted by the AirnodeRrpV0 contract. During the next run cycle, Airnode gets the request parameters from the emitted event.

An Airnode is a first-party oracle that pushes off-chain API data to your on-chain contract. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the

Coding Requester.sol

The Requester Contract will have two main functions, makeRequest() and fulfill().

The makeRequest() function will call the makeFullRequest() function of the AirnodeRrpV0.sol protocol contract which adds the request to its storage. The targeted off-chain Airnode gathers the request from AirnodeRrpV0.sol’s storage and responds using the fulFill() function of AirnodeRrpV0.sol.

Request Parameters

The makeRequest() function expects the following parameters to make a valid request.

• airnode (address) and endpointId specify the endpoint.
• sponsor and sponsorWallet (addresses) specify which wallet will be used to fulfill the request.
• parameters specify the API and Reserved Parameters (see Airnode ABI specifications for how these are encoded) We will encode the parameters off-chain using @airnode-abi library.

Response Parameters

The callback to the Requester contains two parameters:

• requestId: First acquired when making the request and passed here as a reference to identify the request for which the response is intended.
• data: In case of a successful response, this is the requested data which has been encoded and contains a timestamp in addition to other response data. Decode it using the function decode() from the abi object.

Compiling the Contract

To deploy the Requester Contract, we are going to use Remix IDE. It’s an online IDE that allows developing, deploying and administering smart contracts for EVM Compatible Blockchains.

Make a contract and paste in the Requester.sol code.

Now hit compile on the right side of the dashboard and compile the Smart Contract.

Now we are all set to deploy our Requester.

Deploying the Requester

As we are going to deploy the contract on Polygon Mumbai Testnet, make sure you have enough MATIC in your wallet to deploy the Requester and then fund the sponsorWallet later. You can get some from the Mumbai Faucet.

Head to Deploy and run Transactions and select Injected Provider — MetaMask option under Environment. Connect your MetaMask. Make sure you’re on Mumbai Testnet.

The _rrpAddressis the main airnodeRrpAddress. The RRP Contracts have already been deployed on-chain. You can check for your specific chain here.

Fill in the _rrpAddress and click on Deploy. Confirm the transaction on your MetaMask and wait for it to deploy the Requester Contract.

Make sure you’re on the Polygon Mumbai Testnet

Calling the Requester

As soon as your Contract gets deployed, head on to Deploy & run transactions and click on the dropdown for your Requester under Deployed Contracts.

Now select the makeRequest dropdown to see all the parameters you need to pass in order to make a full request to the Airnode.

Here, you need to pass in your airnode(Airnode address), endpointID, sponsor(The Requester itself),sponsorWalletand parameters in order to call the makerequest() function.

We can find the airnode in the receipt.json under the output directory that we got when we deployed our Airnode.

The endpointID can be found under the config.json file.

We need to derive the sponsorWallet through the Airnode CLI command that will make the actual call. We also need to fund it with some MATIC to cover the gas cost.

After you’ve set up the Airnode CLI and installed and built all the dependencies and packages, run the following command to derive your sponsorWallet :

Linux:

npx @api3/airnode-admin derive-sponsor-wallet-address \
  --airnode-xpub xpub6CUGRUo... \
  --airnode-address 0xe1...dF05s \
  --sponsor-address 0xF4...dDyu9

Windows:

npx @api3/airnode-admin derive-sponsor-wallet-address ^
  --airnode-xpub xpub6CUGRUo... ^
  --airnode-address 0xe1...dF05s ^
  --sponsor-address 0xF4...dDyu9

Your airnode-addressand airnode-xpub (The Airnode’s extended public key) can be found in the same receipt.json. The sponsor-address will be the address of the Requester contract itself (the one that you just deployed).

Run the command to obtain your sponsorWallet.

Fund the sponsorWallet with some test MATIC.

The parameters are required to be encoded in bytes32 before you send it. We are going to use the @airnode-abi library for encoding the parameters off-chain and then sending it to the Requester.

You can head over and clone this tutorial’s repository and set it up.

Run the following command to get your encoded parameters :

node .\src\encodeParams.js

Now you have all the parameters that you require to run the makeRequest function. Populate all the fields and click on Transact.

Note: The sponsor here will be the address of the Requester Contract that you just deployed.

Click on transact, confirm the transaction on MetaMask and wait for the transaction to complete.

Now you can head over to https://mumbai.polygonscan.com and check your sponsorWallet for any new transactions.

You might need to wait for a while as the Airnode calls the fulfill() function in AirnodeRrpV0.sol that will in turn call back the requester contract at fulfillAddress using function fulfillFunctionId to deliver data.

Here, we can see our latest Fulfill transaction.

Now go back on Remix and check for requestId under logs for the latest transaction.

You can also find your requestId under logs in the Polygon Mumbai Block Explorer.

Copy your requestId and paste it on under the fulfilledData method to decode the response. Click on call and it will show you your API response.

Here, we requested Tesla’s Stock price.

Now you successfully deployed an Airnode and made a Requester Contract to get data from it. You can also refer to this Repo for all the code that I’ve used for this tutorial.

Any questions? Check out API3’s Discord Server and drop your queries in the dev-support channel!