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 , you can have first-party oracles that are directly operated by the API Providers, called that provides data to any on-chain dApp*.* As a result, you can easily make any REST API accessible to a Smart Contract. API3 Airnodes Say Hello to ChainAPI is a platform that enables you to integrate and deploy the open-source Airnode with its step-by-step integration and deployment tools. ChainAPI To get started, go to and log in by connecting your MetaMask. ChainAPI ChainAPI 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 endpoints to retrieve stock data. dxFeed’s public REST API 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 endpoint with some query parameters. You can add all the parameters that your API requires. GET /events.json 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 param as I want it to return the response in . format fixed json 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. Reserved parameters 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: contains and . config config.json secrets.env The file is used during the deployment/redeployment of an Airnode to configure its behavior and to provide mappings of API operations. config.json The file holds values for config.json that must be kept secret. secrets.env The output directory will have the that will be generated after you successfully deploy the Airnode. receipt.json The file holds AWS credentials for deployments targeted to AWS. aws.env 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 if you are not sure how to obtain them. video The contains all the steps to deploy the airnode provided in a markdown format. README.md Open aws.env and add your and that you just created. AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY Open 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. config/secrets.env 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 * *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. HttpGateway One final step before deploying your Airnode is to set in the file. Authorizers config.json 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 so that any requester contract can access the Airnode config.json 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 on your system. Follow through the Readme to install and build all the dependencies and packages to be able to access the Airnode CLI. Airnode Monorepo 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 ( ) 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. RRP protocol contract AirnodeRrpV0.sol <https://docs.api3.org/airnode/v0.8/grp-developers/ ](https://docs.api3.org/airnode/v0.8/grp-developers/) A * *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. Requester The Requester then calls the protocol contract, which emits a blockchain event with the request parameters. Airnode listens to the events emitted by the contract. During the next run cycle, Airnode gets the request parameters from the emitted event. AirnodeRrpV0 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 ( ) that adds the RRP protocol contract AirnodeRrpV0.sol Coding Requester.sol The Requester Contract will have two main functions, and . makeRequest() fulfill() The function will call the function of the protocol contract which adds the request to its storage. The targeted off-chain gathers the request from AirnodeRrpV0.sol’s storage and responds using the function of AirnodeRrpV0.sol. makeRequest() makeFullRequest() AirnodeRrpV0.sol Airnode fulFill() Request Parameters The function expects the following parameters to make a valid request. makeRequest() (address) and specify the endpoint. airnode endpointId and (addresses) specify which wallet will be used to fulfill the request. sponsor sponsorWallet specify the API and (see for how these are encoded) We will encode the parameters off-chain using library. parameters Reserved Parameters Airnode ABI specifications @airnode-abi Response Parameters The callback to the contains two parameters: Requester : First acquired when making the request and passed here as a reference to identify the request for which the response is intended. requestId : In case of a successful response, this is the requested data which has been encoded and contains a in addition to other response data. Decode it using the function from the object. data timestamp decode() abi Compiling the Contract To deploy the Requester Contract, we are going to use . It’s an online IDE that allows developing, deploying and administering smart contracts for EVM Compatible Blockchains. Remix IDE Make a contract and paste in the code. Requester.sol 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 later. You can get some from the . sponsorWallet 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 is the main The RRP Contracts have already been deployed on-chain. You can check for your specific chain . _rrpAddress airnodeRrpAddress. here Fill in the and click on Deploy. Confirm the transaction on your MetaMask and wait for it to deploy the Requester Contract. _rrpAddress 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 dropdown to see all the parameters you need to pass in order to make a full request to the Airnode. makeRequest Here, you need to pass in your (Airnode address), , (The Requester itself), and in order to call the function. airnode endpointID sponsor sponsorWallet parameters makerequest() We can find the in the under the output directory that we got when we deployed our Airnode. airnode receipt.json The can be found under the file. endpointID config.json We need to derive the 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. sponsorWallet 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 and (The extended public key) can be found in the same The will be the address of the Requester contract itself (the one that you just deployed). airnode-address airnode-xpub Airnode’s receipt.json. sponsor-address Run the command to obtain your . sponsorWallet Fund the with some test MATIC. sponsorWallet The parameters are required to be encoded in before you send it. We are going to use the library for encoding the parameters off-chain and then sending it to the Requester. bytes32 @airnode-abi You can head over and clone and set it up. this tutorial’s repository 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 function. Populate all the fields and click on Transact. makeRequest 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 and check your for any new transactions. https://mumbai.polygonscan.com sponsorWallet 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 transaction. Fulfill Now go back on Remix and check for under logs for the latest transaction. requestId You can also find your under logs in the Polygon Mumbai Block Explorer. requestId Copy your and paste it on under the method to decode the response. Click on call and it will show you your API response. requestId fulfilledData 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 for all the code that I’ve used for this tutorial. this Repo Any questions? Check out and drop your queries in the dev-support channel! API3’s Discord Server

Polygon

Chain

API3

YouTube

Smart Contract Tutorial for Beginners — Lottery dAPP [Part 1]

The Rising Importance of First-Party Oracles

Connect your dApps our 150+ Web3 enabled APIs

Nominated for 2022 - HackerNoon Contributor of the Year - Api

Nominated for 2022 - HackerNoon Contributor of the Year - Smart Contracts

Too Long; Didn't Read

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

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

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Bitcoin Alliance to Support El Salvador’s Recent Adoption of Crypto-Friendly Financial Services

Redefining Trust: Smart Escrow Contracts

Bitcoin Alliance to Support El Salvador’s Recent Adoption of Crypto-Friendly Financial Services

Developers Unite for the First Bitcoin Banking Hackathon, Happening in El Salvador

How to Migrate to dAPIs - A Developers Guide on Switching Your Oracle

How you can use Quantum random numbers as a public good, on 13 smart contract protocols

Bitcoin Alliance to Support El Salvador’s Recent Adoption of Crypto-Friendly Financial Services

Redefining Trust: Smart Escrow Contracts

Bitcoin Alliance to Support El Salvador’s Recent Adoption of Crypto-Friendly Financial Services

Developers Unite for the First Bitcoin Banking Hackathon, Happening in El Salvador

How to Migrate to dAPIs - A Developers Guide on Switching Your Oracle

How you can use Quantum random numbers as a public good, on 13 smart contract protocols

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps