Documentation
A newer release of the API3 Technical documentation is available.
📂 Reference > Packages

# Admin CLI

Table of Contents

Use the airnode-admin (opens new window) Admin CLI tool to interact with Airnode across blockchains. There are commands for both developers (dApp) and API providers. Developers can sponsor requester contracts and derive sponsorWallets for Airnodes. API providers can build Airnodes that serve their API data to requester contracts.

Transaction Gas Costs

Some commands will incur transaction fees. These are per call transaction gas costs and are relatively small. See the Developer Fees doc.

Almost all commands require you to provide a blockchain providerUrl. Following are just two examples of many possibilities. See the Chain Providers doc for more information.

  • https://eth-rinkeby.gateway.pokt.network/v1/lb/<APP_ID>
  • https://ropsten.infura.io/v3/<KEY>

The CLI connects to the AirnodeRrp.sol (opens new window) or the RequesterAuthorizerWithAirnode.sol (opens new window) contract, which addresses are derived from the current chain. You can optionally specify the contract addresses yourself by providing optional airnode-rrp-address or requester-authorizer-with-airnode command argument with the address of the deployed contract on your targeted chain.

Commands that require mnemonic will make an on-chain transaction. The application will derive the account from the mnemonic with default ethereum derivation path m/44'/60'/0'/0/0. You can override this by using the optional parameter derivation-path (m/44'/60'/0'/0/...). Make sure that the wallet that is associated with the mnemonic is funded on the target chain. The application will not exit until the transaction is confirmed.

# Using transaction overrides

CLI commands also support the following transaction overrides as optional arguments: gas-limit, gas-price (legacy transactions), max-fee and max-priority-fee (EIP-1559 transactions) and nonce.

# Default transaction overrides

If no overrides are provided, transactions will default to the following values:

EIP-1559 transactions

maxPriorityFeePerGas: 3.12 gwei
maxFeePerGas: baseFeePerGas of the last block * 2 + maxPriorityFeePerGas
1
2

Legacy transactions

gasPrice: gasPrice returned by the ethers getGasPrice method
1

# Using npx

View all commands:

npx @api3/airnode-admin --help
1

View the parameters of a command:

npx @api3/airnode-admin $COMMAND --help
1

# Using Docker

Use the Admin CLI docker image as an alternative to npx:

docker run api3/airnode-admin:0.5.2 --help
1

View the parameters of a command:

docker run api3/airnode-admin:0.5.2 $COMMAND --help
1

# SDK

You can also use the package programmatically. The SDK exports respective functions for all CLI commands as well as helper functions for obtaining the contract instance on the targeted chain.

import { sponsorRequester, getAirnodeRrpWithSigner } from '@api3/airnode-admin';
// First obtain the contract instance on target chain
const airnodeRrp = await getAirnodeRrpWithSigner(
  mnemonic,
  derivation - path,
  providerUrl,
  airnodeRrpAddress
);
// Pass the contract instance as the first argument to the SDK function
const requester = await sponsorRequester(airnodeRrp, requester);
1
2
3
4
5
6
7
8
9
10
11

If you plan to use multiple commands it might be tedious to pass the contract instance to every function call. For this reason there is also class based AdminSdk which you initialize with AirnodeRrp contract only once.

import { AdminSdk } from '@api3/airnode-admin';
// First initialize the SDK with AirnodeRrp contract instance.
// You can use static AdminSdk functions or provide your own instance.
const airnodeRrp = await AdminSdk.getAirnodeRrpWithSigner(
  mnemonic,
  derivation - path,
  providerUrl,
  airnodeRrpAddress
);
// Create sdk instance
const adminSdk = new AdminSdk(airnodeRrp);
// Call the method you need
const requester = await adminSdk.sponsorRequester(requester);
// You can switch the contract instance anytime. E.g. if you are using ethers
adminSdk.airnodeRrp = airnodeRrp.connect(someOtherWallet);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

The SDK will also provide TS typings out of the box. Please, refer to the implementation for more details.

# Using transaction overrides

You can also use transaction overrides to customize gas limits and fee settings. The SDK simply passes the overrides parameter to the contract method so you can use any overrides supported by the ethers library.

import { ethers } from 'ethers';
// Legacy transaction overrides
const overrides = {
  gasLimit: ethers.BigNumber.from('200000'),
  gasPrice: ethers.utils.parseUnits('20', 'gwei')
};
// EIP-1559 transaction overrides
const overrides = {
  gasLimit: ethers.BigNumber.from('200000'),
  maxFeePerGas: ethers.utils.parseUnits('20', 'gwei')
  maxPriorityFeePerGas: ethers.utils.parseUnits('10', 'gwei')
};
// The transaction overrides parameter is optional and can be passed in as the last parameter
const requester = await adminSdk.sponsorRequester(requester, overrides);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Sponsors

Commands related to a sponsor's relationships between requesters and sponsorWallets as well as templates used by a sponsor's requesters. Some of these commands connect to the AirnodeRrp.sol (opens new window) protocol contract where the signer is sponsor account.

Sponsors a requester contract so that its requests can be fulfilled by the sponsorWallet of an Airnode. The account derived from the mnemonic you provide must belong to the sponsor.

Sponsoring a requester and using the returned sponsorAddress to derive a sponsorWallet for an Airnode creates a relationship between the requester and the Airnode, see the derive-sponsor-wallet-address command.

  • provider-url: A valid blockchain provider URL.
  • sponsor-mnemonic: A wallet owned by the sponsor. Used to derive a sponsorAddress as the default account of the mnemonic unless a derivation-path is specified. It's also used to pay gas costs from the mnemonic's default account unless a derivation-path is specified.
  • requester-address: The contract address of the requester to sponsor.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.
  • derivation-path (optional): Selects an alternate account to use from the mnemonic rather than the default.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# unsponsor-requester

Removes the sponsorship of a requester contract so that its requests can no longer be fulfilled by the sponsorWallet. The account derived from the mnemonic you provide here has to belong to the sponsor.

  • provider-url: A valid blockchain provider URL.
  • sponsor-mnemonic: A wallet owned by the sponsor. Must be the mnemonic used to sponsor the requester. Used to pay gas costs from the mnemonic's default account unless a derivation-path is specified.
  • requester-address: The contract address of the requester to unsponsor.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.
  • derivation-path (optional): Selects an alternate account to use from the mnemonic rather than the default.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# get-sponsor-status

Returns the sponsor status for a given sponsor and requester (true if sponsored, false otherwise).

  • provider-url: A valid blockchain provider URL.
  • sponsor-address: The sponsorAddress returned when the requester was sponsored.
  • requester-address: The requester contract address.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.

# derive-sponsor-wallet-address

Derives the address of the wallet designated by an Airnode for a sponsor, which is called the sponsorWallet. This command will error if airnode-xpub does not belong to the HDNode with the path m/44'/60'/0' of the Airnode wallet. See the derive-airnode-xpub command.

  • airnode-xpub: The extended public address of the Airnode for path m/44'/60'/0'.
  • airnode-address: The public address of the Airnode.
  • sponsor-address: The address of the sponsor account.

# create-template

Reads a file, uses its contents to create a template and returns a template-id. Also see Using Templates for an example template file.

  • provider-url: A valid blockchain provider URL.
  • mnemonic: Used to pay gas costs from the mnemonic's default account unless a derivation-path is specified.
  • template-file-path: Path to the template file to create on-chain.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.
  • derivation-path (optional): Selects an alternate account to use from the mnemonic rather than the default.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# get-template

Returns the template for the given template-id.

  • provider-url: A valid blockchain provider URL.
  • template-id: The id of a template to return.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.

# request-withdrawal

Requests a withdrawal from a sponsorWallet managed by an Airnode.

The funds will be returned to the account derived from the sponsor-mnemonic. This account must belong to a sponsor for the specified sponsor wallet address in the command.

After the request is made, it needs to be fulfilled by Airnode, so the return value of this command is only a withdrawal-request-id which you can use to call check-withdrawal-request to see whether the request was processed or not.

Withdrawal Priority

Airnode will drop any pending API calls associated with a sponsorWallet once a withdrawal is requested.

  • provider-url: A valid blockchain provider URL.
  • sponsor-mnemonic: A wallet owned by the sponsor. Used to pay gas costs from the mnemonic's default account unless a derivation-path is specified. Withdrawn funds will be added to this mnemonic's default address unless a derivation-path is specified.
  • airnode-address: The public address of the Airnode.
  • sponsor-wallet-address: The pubic address of the sponsorWallet to withdraw from. This address was returned by the derive-sponsor-wallet-address command.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.
  • derivation-path (optional) : The destination address of the mnemonic parameter to add the withdrawn funds to if the default address is not desired.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# check-withdrawal-request

Checks the status of the withdrawal request with the given withdrawal-request-id from the request withdrawal command above.

  • provider-url: A valid blockchain provider URL.
  • withdrawal-request-id: This id was returned by the request-withdrawal command.
  • airnode-rrp-address (optional): The public address of the AirnodeRrp.sol protocol contract.

# verify-airnode-xpub

Verifies that the airnode-xpub belongs to the HDNode with the path m/44'/60'/0' of the Airnode wallet. This command checks that the Airnode address can be derived with provided Airnode xpub with default derivation path m/44'/60'/0'/0/0 and compares it with the airnode-address. This command will most likely be used by a sponsor to verify that the xpub belongs to the Airnode before calling the derive-sponsor-wallet-address command.

# Airnodes

Helper commands for a previously deployed Airnode. Some of these commands connect to the AirnodeRrp.sol protocol contract where the signer must be the Airnode wallet.

# derive-airnode-xpub

Derives the Airnode extended public key (xpub). This xpub must be announced via off-chain channels because it will be needed to derive a sponsorWallet address. See the derive-sponsor-wallet-address command.

  • airnode-mnemonic: The Airnode mnemonic for which the xpub is to be derived.

# derive-endpoint-id

Derives an endpointId from the OIS title and the endpoint's name. This command uses the convention described in the triggers section of the configuring airnode documentation. Add the endpointId to the config.json file (triggers.rrp[n].endpointId).

  • ois-title: The title of the OIS from config.json (ois.title).
  • endpoint-name: The name of the endpoint from config.json (triggers.rrp[n].endpointName).

# generate-mnemonic

Generates a unique mnemonic which can be used to create an airnode wallet. In addition to the mnemonic, this command will also display the corresponding airnode address and its extended public key (xpub).

npx @api3/airnode-admin generate-mnemonic
1

# derive-airnode-address

Derives the airnode address which is the identifier of the particular Airnode on chain. The address is the default address of a BIP 44 wallet (with the path m/44'/60'/0'/0/0). Use this identifier for many other admin CLI commands, such as derive-sponsor-wallet-address.

  • airnode-mnemonic: A mnemonic used to generate the airnode address.

# RequesterAuthorizerWithAirnode

RequesterAuthorizerWithAirnode contract was written by API3 as an authorizer contract that can be used by any Airnode. Airnode owners can use this contract in addition to authorizer contracts they have written themselves.

This authorizer contract can whitelist requesters where each Airnode is adminned by themselves.

These commands connect to the RequesterAuthorizerWithAirnode.sol (opens new window) contract.

# set-whitelist-expiration

Called by the Airnode wallet or a whitelist expiration setter to set the whitelisting expiration of a requester for the Airnode–endpoint pair. This can hasten expiration in the case the new expiration timestamp is prior to a previously set timestamp.

  • mnemonic: Used to pay gas costs from the mnemonic's default account unless a derivation-path is specified. The mnemonic must be at least an Admin or Airnode wallet.
  • provider-url: A valid blockchain provider URL.
  • endpoint-id: The endpointId for which permission is granted (from OIS).
  • requester-address: The public address of the requester contract.
  • expiration-timestamp: A unix formatted timestamp.
  • airnode-address: The public address of the Airnode.
  • requester-authorizer-with-airnode (optional): The authorizer contract address.
  • derivation-path (optional): Selects an alternate account to use from the mnemonic rather than the default.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# extend-whitelist-expiration

Called by the Airnode wallet or a whitelist expiration extender to extend the whitelist expiration of a requester for the Airnode–endpoint pair. This command expects that the new expiration timestamp is later then the previously set timestamp.

  • mnemonic: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet.
  • provider-url: A valid blockchain provider URL.
  • endpoint-id: The endpointId for which permission is granted (from OIS).
  • requester-address: The public address of the requester contract.
  • expiration-timestamp: A unix formatted timestamp.
  • airnode-address: The public address of the Airnode.
  • requester-authorizer-with-airnode (optional): The authorizer contract address.
  • derivation-path (optional): Selects an alternate account to use from the mnemonic rather than the default.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# set-indefinite-whitelist-status

Called by the Airnode wallet or an indefinite whitelister to whitelist a requester indefinitely for the Airnode–endpoint pair. This command can be used to make whitelisting permanent in cases where it is needed to allow requests even beyond the expiration period.

  • mnemonic: Used to pay on-chain gas cost for this command's transaction. The mnemonic must be at least an Admin or Airnode wallet. The default address of the mnemonic will be used unless a derivation-path is provided.
  • provider-url: A valid blockchain provider URL.
  • endpoint-id: The endpointId for which permission is granted (from OIS).
  • requester-address: The public address of the requester contract.
  • expiration-timestamp: A unix formatted timestamp.
  • airnode-address: The public address of the Airnode.
  • requester-authorizer-with-airnode (optional): The authorizer contract address.
  • derivation-path (optional): Selects an alternate account to use from the mnemonic rather than the default.
  • indefinite-whitelist-status: Whether the Airnode-endpoint pair should be whitelisted indefinitely or not.
  • gas-limit (optional): The gas limit to use for the transaction.
  • gas-price (optional): The gas price (in gwei) to use for the transaction (only for legacy transactions).
  • max-fee (optional): The maximum fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • max-priority-fee (optional): The maximum priority fee (in gwei) per gas to use for the transaction (only for EIP-1559 transactions).
  • nonce (optional): The nonce to use for the transaction.

# get-whitelist-status

Called to get the detailed whitelist status of a requester for the Airnode–endpoint pair.

  • provider-url: A valid blockchain provider URL.
  • endpoint-id: The endpointId for which permission is granted (from OIS).
  • requester-address: The public address of the requester contract.
  • airnode-address: The public address of the Airnode.
  • requester-authorizer-with-airnode (optional): The authorizer contract address.

# is-requester-whitelisted

Called to check if a requester is whitelisted to use the Airnode–endpoint pair.

  • provider-url: A valid blockchain provider URL.
  • requester-authorizer-with-airnode: The authorizer contract address.
  • endpoint-id: The endpointId for which permission is granted (from OIS).
  • requester-address: The public address of the requester contract.
  • airnode-address: The public address of the Airnode.

# More Examples

You can find more examples in the @api3-dao/airnode/package/admin test files (opens new window).

Last Updated: 8/9/2022, 2:28:25 PM

← ABI →