by Vansh Wassan, Integrations Engineer & Developer Relations @ API3
Twitter: @WassanVansh Github:
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
Say Hello to ChainAPI
To get started, go to 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
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.
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
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 *
One final step before deploying your Airnode is to set
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
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
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
A *
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
Coding Requester.sol
The Requester Contract will have two main functions, makeRequest() and fulfill().
The makeRequest() function will call the makeFullRequest() function of the fulFill() function of AirnodeRrpV0.sol.
Request Parameters
The makeRequest() function expects the following parameters to make a valid request.
airnode(address) andendpointIdspecify the endpoint.sponsorandsponsorWallet(addresses) specify which wallet will be used to fulfill the request.parametersspecify the API andReserved Parameters (seeAirnode ABI specifications for how these are encoded) We will encode the parameters off-chain using@airnode-abilibrary.
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 atimestamp in addition to other response data. Decode it using the functiondecode()from theabiobject.
Compiling the Contract
To deploy the Requester Contract, we are going to use
Make a contract and paste in the
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
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
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
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 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
Any questions? Check out