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

# Admin CLI Commands

Table of Contents

Use the 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.

  • 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 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.

View all commands:

npx @api3/airnode-admin --help
1

View the parameters of a command:

npx @api3/airnode-admin $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.

# 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 (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.

# 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 (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.

# 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 (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 (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.

# 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 (optional): The public address of the AirnodeRrp.sol protocol contract.

# request-withdrawal

Requests a withdrawal from a sponsorWallet managed by an Airnode and returns a withdrawal-request-id for tracking purposes. The default account derived from the mnemonic will be used to return the funds.

  • 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 (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.

# check-withdrawal-request

Checks the status of the withdrawal request with the given ID (withdrawal-request-id).

  • provider-url: A valid blockchain provider URL.
  • withdrawal-request-id: This id was returned by the request-withdrawal command.
  • airnode-rrp (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).

# 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.

# 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.

# 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.

# 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

← Airnode ABI →