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

# config.json

Table of Contents

The config.json defines a single Airnode deployment. The file contents are a single JSON object. Each config object can be thought of as the static NoSQL database of an Airnode deployment. It contains five fields as show below.

{
  "chains": [],
  "nodeSettings": {},
  "triggers": {},
  "templates": [],
  "ois": [],
  "apiCredentials": []
}
1
2
3
4
5
6
7
8
  • chains: Blockchains the Airnode deployment will serve on and configuration details
  • nodeSettings: General deployment parameters such as node version and deployment configuration.
  • triggers: Which on-chain endpoints will be usable by which an available protocol (currently only RRP) and under what endpoint ID.
  • templates:
  • ois: API specifications and the corresponding on-chain endpoints, kept as OIS objects.
  • apiCredentials: Which API credentials will be usable by which OIS and security scheme.

# chains

Lists the blockchains the Airnode deployment will serve on and specifies respective parameters.

// chains
[
  {
    "authorizers": [
      "0xf18c105D0375E80980e4EED829a4A68A539E6178",
      "0xCE5e...1abc"
    ],
    "contracts": {
      "AirnodeRrp": "0xa0AD79D995DdeeB18a14eAef56A549A04e3Aa1Bd"
    },
    "id": "1",
    "providers": {
      "selfHostedMainnet": {
        "url": "${CP_SELF_HOSTED_MAINNET_URL}"
      },
      "infuraMainnet": {
        "url": "${CP_INFURA_MAINNET_URL}"
      }
    },
    "type": "evm",
    "options": {
      "txType": "eip1559",
      "priorityFee": {
        "value": 3.12,
        "unit": "gwei"
      },
      "baseFeeMultiplier": 2,
      "fulfillmentGasLimit": 500000
    },
    "maxConcurrency": 100,
    "blockHistoryLimit": 300,
    "minConfirmations": 0
  },
  {
    "authorizers": [],
    "contracts": {
      "AirnodeRrp": "0xa0AD79D995DdeeB18a14eAef56A549A04e3Aa1Bd"
    },
    "id": "3",
    "providers": {
      "infuraRopsten": {
        "url": "${CP_INFURA_ROPSTEN_URL}"
      }
    },
    "type": "evm",
    "options": {
      "txType": "eip1559",
      "priorityFee": {
        "value": 3.12,
        "unit": "gwei"
      },
      "baseFeeMultiplier": 2,
      "fulfillmentGasLimit": 500000,
      "withdrawalRemainder": {
        "value": 0,
        "unit": "wei"
      }
    },
    "maxConcurrency": 100,
    "blockHistoryLimit": 300,
    "minConfirmations": 0
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# authorizers

(required) - The list of authorizer contract addresses specifying the authorization patterns that the Airnode should use. An empty array would allow-all. See the Authorization doc for more information.

# contracts

(required) - An object that keeps the addresses of the protocol contracts deployed on the respective chain. It must include the AirnodeRrp contract address. Although you can deploy these contracts yourself, you are recommended to use the ones that were deployed by API3 listed here.

# id

(required) - The corresponding chain (or network) ID. If this is an Ethereum-based chain, id should be the chain ID as described in EIP-155 (opens new window). Refer to the documentations of the chain you will be using to find its chain ID. Supported chains are listed under Airnode Contract Addresses.

# providers

(required) - List of chain providers. Note that multiple can be used simultaneously. The Airnode deployment will expect to find the URLs of each of these chain providers in their respective url fields. It is generally recommended to provide url via interpolation from the secrets.env file.

# type

(required) - The type of chain. Currently only evm is supported.

# options

(required) - An object that configures chain-related options. See Configuring an Airnode for some considerations.

# options.txType

(required) - The transaction type to use:

# options.priorityFee

(optional) - An object that configures the EIP-1559 Priority Fee. Defaults: {"value": 3.12, "unit": "gwei"}.

# options.priorityFee.value

(required) - A number specifying the EIP-1559 priority fee value.

# options.priorityFee.unit

(required) - The unit of the priority fee value. It can be one of the following:

  • wei
  • kwei
  • mwei
  • gwei
  • szabo
  • finney
  • ether

# options.baseFeeMultiplier

(optional) - Number multiplied by the Base Fee to yield the Maximum Fee for EIP-1559 transactions. Defaults to: 2.

The resulting Maximum Fee will equal (Base Fee * baseFeeMultiplier) + priorityFee

# options.gasPriceMultiplier

(optional) - Number with a maximum of two decimals that gets multiplied by the legacy gas price. No multiplier is used by default.

The resulting Gas Price will equal Gas Price * gasPriceMultiplier

# options.fulfillmentGasLimit

(required) - The maximum gas limit allowed when Airnode responds to a request, paid by the requester. If exceeded, the request is marked as failed and will not be repeated during Airnode's next run cycle.

# options.withdrawalRemainder

(optional) - An object of the form {"value": 0, "unit": "wei"} that configures the amount to subtract from the funds returned to the sponsor when making a withdrawal. Defaults to zero and is relevant only for some chains e.g. Optimism.

# options.withdrawalRemainder.value

(required) - A number specifying the withdrawalRemainder value.

# options.withdrawalRemainder.unit

(required) - The unit of the withdrawalRemainder value. It can be one of the following:

  • wei
  • kwei
  • mwei
  • gwei
  • szabo
  • finney
  • ether

# maxConcurrency

(required) - The maximum number of concurrent handler calls per single Airnode invocation. Airnode is reserving (AWS (opens new window)) and limiting (AWS (opens new window), GCP (opens new window)) the number of spawned cloud functions based on this field.

If you want to disable this behavior, see disableConcurrencyReservations.

See Configuring an Airnode for additional considerations.

# blockHistoryLimit

(optional) - The number of blocks in the past that the Airnode deployment should search for requests. Defaults to 300 (roughly 1 hour for Ethereum).

# minConfirmations

(optional) - The number of confirmations required for a request to be considered valid. Minimum confirmations refers to the number of blocks that have elapsed since the current confirmed block. Defaults to 0.

# nodeSettings

An object containing general deployment parameters of an Airnode.

// nodeSettings
{
  "nodeVersion": "0.7.5",
  "cloudProvider": {
    "type": "gcp",
    "region": "us-east1",
    "disableConcurrencyReservations": false,
    "projectId": "${GCP_PROJECT_ID}"
  },
  "stage": "testnet",
  "airnodeWalletMnemonic": "${AIRNODE_WALLET_MNEMONIC}",
  "heartbeat": {
    "enabled": true,
    "url": "${HEARTBEAT_URL}",
    "apiKey": "${HEARTBEAT_API_KEY}",
    "id": "${HEARTBEAT_ID}"
  },
  "httpGateway": {
    "enabled": true,
    "apiKey": "${HTTP_GATEWAY_API_KEY}",
    "maxConcurrency": 20
  },
  "httpSignedDataGateway": {
    "enabled": true,
    "apiKey": "${HTTP_SIGNED_DATA_GATEWAY_API_KEY}",
    "maxConcurrency": 20
  },
  "logFormat": "json",
  "logLevel": "INFO"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# cloudProvider

(required) - The cloud provider that the node will be deployed at and its configuration. Learn more about AWS or GCP resources that Airnode uses in the Cloud Resources documentation.

# cloudProvider.type

(required) - Currently aws and gcp are supported for serverless (deployer-image). Use local if you want to run Airnode as a docker container locally (client-image).

# cloudProvider.region

(required for AWS and GCP) - The cloud provider region that Airnode will be deployed to. An example AWS value would be us-east-1 and an example GCP value would be us-east1. See the cloud provider's documentation for possible values, though not all regions can be deployed to. For GCP, make sure to choose a region and not a zone, and see the list below for regions that have been confirmed to work. For AWS, some regions are disabled by default and you must enable them (opens new window) before you can create and manage resources. Note that transferring a deployment from one region to the other is not trivial (i.e., it does not take one command like deployment, but rather three) and is not advised. See Cloud Resource for a list of supported regions.

# cloudProvider.disableConcurrencyReservations

(required for AWS and GCP) - Disables concurrency reservations for spawned cloud functions. For more information refer to the maxConcurrency section.

# cloudProvider.projectId

(required for GCP) - Project ID of the GCP project the Airnode will be deployed under.

# airnodeWalletMnemonic

(required) - The wallet mnemonic that will be used as the Airnode's BIP 44 wallet from which the Airnode's address will be derived. It is not required to fund the wallet to run the Airnode but must be funded to announce the xpub of the Airnode on-chain which is optional.

# heartbeat

(required) - Object configuring Airnode's heartbeat functionality. Airnode can periodically make a request to the specified URL signaling that it's active at the end of each cycle (every minute). There are plans in the future to allow the sending of a payload with information for reporting purposes. See the Heartbeat documentation for more information.

# heartbeat.enabled

(required) - Enable or disable, using true or false, Airnode's heartbeat.

# heartbeat.apiKey

(only if enabled) - The API key to authenticate against the heartbeat URL.

# heartbeat.id

(only if enabled) - The Airnode heartbeat ID for accounting purposes.

# heartbeat.url

(only if enabled) - The URL to make the heartbeat request to.

# httpGateway

(required) - The Airnode's HTTP gateway can request endpoints without using the blockchain. See the HTTP Gateways documentation for more info.

# httpGateway.enabled

(required) - Enable or disable, using true or false, Airnode's access to the HTTP gateway.

# httpGateway.apiKey

(only if enabled) - The API key to authenticate against the gateway. The key must have a length of between 30 - 120 characters. Do not use the same key for httpGateway and httpSignedDataGateway.

# httpGateway.maxConcurrency

(only if enabled, optional) - A number higher than zero representing the maximum number of serverless functions serving HTTP gateway requests running at the same time. When omitted, there is no maximum concurrency set.

# httpSignedDataGateway

(required) - The Airnode's HTTP gateway can request endpoints without using the blockchain. See the HTTP Gateways documentation for more info.

# httpSignedDataGateway.enabled

(required) - Enable/disable, using true/false, Airnode's access to the HTTP gateway.

# httpSignedDataGateway.apiKey

(only if enabled) - The API key to authenticate against the gateway. The key must have a length of between 30 - 120 characters. Do not use the same key for httpGateway and httpSignedDataGateway.

# httpSignedDataGateway.maxConcurrency

(only if enabled, optional) - A number higher than zero representing the maximum number of serverless functions serving HTTP gateway requests running at the same time. When omitted, there is no maximum concurrency set.

# logFormat

(required) - The format that will be used to output logs. Either json or plain.

# logLevel

(required) - The highest verbosity level of the logs that will be outputted. Options: DEBUG, INFO, WARN or ERROR.

# nodeVersion

(required) - The version of the node (Airnode) that will be deployed with this config object, of the form #.#.#. Since the config.json format may change with node versions, always match the config.json version with the Airnode being deployed. See the Releases page of the Airnode repo (opens new window) for available versions.

# stage

(required) - The label used to distinguish between multiple deployments of the same Airnode on a cloud provider. For example, the same Airnode may have multiple deployments with stage set to a different value (dev, public, prod). stage cannot be longer than 16 characters and can only include lowercase alphanumeric characters (a–z, 0–9) and hyphens (-).

# triggers

An array that maps external triggers such as a request made through RRP (or a subscription made through PSP, which is not implemented yet) to an endpoint defined in an OIS.

// triggers
{
  "rrp": [
    {
      "endpointId": "0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838",
      "oisTitle": "myOisTitle",
      "endpointName": "myEndpointName"
    }
  ],
  "http": [
    {
      "endpointId": "0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838",
      "oisTitle": "myOisTitle",
      "endpointName": "myEndpointName"
    }
  ],
  "httpSignedData": [
    {
      "endpointId": "0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838",
      "oisTitle": "myOisTitle",
      "endpointName": "myEndpointName"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

In the example above, the Airnode deployment has an OIS with the title myOisTitle. This OIS has an endpoint with the name myEndpointName. When the Airnode deployment detects a request that references its airnodeAddress and 0xd7ddc8ee64d6e540682ec844a5dd9737663ec3afe5751102eb4f966744751838 as the endpointId, it will call the specified endpoint (myOisTitle-myEndpointName) with the parameters provided in the request to fulfill it. See the endpoint id documentation for the default convention for deriving the endpointId.

# rrp

(required) - An array of endpoints from OIS that the Airnode will respond to via the RRP protocol AirnodeRrpV0.sol.

# rrp[n].endpointId

(required) - A identifier derived for an oisTitle/endpointName pair. For derivation see: derive-endpoint-id.

# rrp[n].oisTitle

(required) - The title of an OIS object.

# rrp[n].endpointName

(required) - The endpoint name of an OIS endpoint.

# http

(required) - An array of endpoints from OIS that the Airnode will respond to via the HTTP gateway.

# http[n].endpointId

(required) - A identifier derived for an oisTitle/endpointName pair. For derivation see: derive-endpoint-id.

# http[n].oisTitle

(required) - The title of an OIS object.

# http[n].endpointName

(required) - The endpoint name of an OIS endpoint.

# httpSignedData

(required) - An array of endpoints from OIS that the Airnode will respond to via the HTTP Signed Data Gateway.

# httpSignedData[n].endpointId

(required) - A identifier derived for an oisTitle/endpointName pair, see derive-endpoint-id.

# httpSignedData[n].oisTitle

(required) - The title of an OIS object.

# httpSignedData[n].endpointName

(required) - The endpoint name of an OIS endpoint.

# templates

An array that includes the necessary information to make template requests

// templates
[
  {
    "templateId": "0x02834eb43d56133982b7d6e5aa8b466c7ea4ba0fadf697698c1fee0996bba0fc",
    "endpointId": "0xd9e8c9bcc8960df5f954c0817757d2f7f9601bd638ea2f94e890ae5481681153",
    "encodedParameters": "0x3173000000000000000000000000000000000000000000000000000000000000636f696e49640000000000000000000000000000000000000000000000000000657468657265756d000000000000000000000000000000000000000000000000"
  }
]
1
2
3
4
5
6
7
8

# templates

(required) - An array of templates which can be left empty if no templates are used. Valid templates will be used to make template requests without calling the contract to fetch the template from the chain. For details see: using templates

# templateId

(required) - An identifier derived by hashing the Airnode address, the endpointId and the encoded parameters of the template. For derivation see: templates.

# endpointId

(required) - An identifier derived for an oisTitle/endpointName pair. For derivation see: derive-endpoint-id.

# encodedParameters

(required) - The encoded request parameters.

# ois

A list of OIS objects. Since each OIS specifies the integration of an API to an oracle, a single Airnode deployment can serve multiple APIs. To avoid duplication of content, see the API Integration guide and the Oracle Integration Specifications (OIS) documentation.

# apiCredentials

Each entry in apiCredentials maps to a security scheme defined in an OIS (ois[n].components.securitySchemes.{securitySchemeName}), where oisTitle is the title field of the related OIS, and securitySchemeName is the name of the respective security scheme. These would be myOisTitle and mySecurityScheme in the example below. securitySchemeValue is the value used for the authentication with the security scheme (e.g., the API key) which would be in secrets.env in the example below. For more implementation details, see the API Security documentation.

The security field in the OIS object must be included and hold the names of all security schemes the API operation

Note that if you do not need a security scheme, leave the apiCredentials array empty.

// apiCredentials
[
  {
    "oisTitle": "myOisTitle",
    "securitySchemeName": "mySecurityScheme",
    "securitySchemeValue": "${SS_MY_API_KEY}"
  }
]
// components and security field in OIS object
{
"title": "myOisTitle",
...,
"components": {
  "securitySchemes": {
    "mySecurityScheme": {
      "in": "header",
      "type": "apiKey",
      "name": "X-api-key"
    }
  }
},
"security": {
  "mySecurityScheme" []
}
...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# oisTitle

(required) - The ois.title of the OIS where the securitySchemeName can be found.

# securitySchemeName

(required) - The name of a security scheme from ois[n].components.securitySchemes.{securitySchemeName}.

# securitySchemeValue

(required) - The value of the security scheme used (as defined by ois[n].components.securitySchemes.{securitySchemeName} for the authentication. Usually stored in secrets.env.

Last Updated: 10/24/2022, 5:58:50 AM

← secrets.env →