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": {
      "requesterEndpointAuthorizers": [
        "0xf18c105D0375E80980e4EED829a4A68A539E6178",
        "0xCE5e...1abc"
      ]
    },
    "authorizations": {
      "requesterEndpointAuthorizations": {}
    },
    "contracts": {
      "AirnodeRrp": "0xa0AD79D995DdeeB18a14eAef56A549A04e3Aa1Bd"
    },
    "id": "1",
    "providers": {
      "selfHostedMainnet": {
        "url": "${CP_SELF_HOSTED_MAINNET_URL}"
      },
      "infuraMainnet": {
        "url": "${CP_INFURA_MAINNET_URL}"
      }
    },
    "type": "evm",
    "options": {
      "fulfillmentGasLimit": 500000,
      "gasPriceOracle": [
        {
          "gasPriceStrategy": "latestBlockPercentileGasPrice",
          "percentile": 60,
          "minTransactionCount": 20,
          "pastToCompareInBlocks": 20,
          "maxDeviationMultiplier": 2
        },
        {
          "gasPriceStrategy": "providerRecommendedGasPrice",
          "recommendedGasPriceMultiplier": 1.2
        },
        {
          "gasPriceStrategy": "providerRecommendedEip1559GasPrice",
          "baseFeeMultiplier": 2,
          "priorityFee": {
            "value": 3.12,
            "unit": "gwei"
          }
        },
        {
          "gasPriceStrategy": "constantGasPrice",
          "gasPrice": {
            "value": 10,
            "unit": "gwei"
          }
        }
      ]
    },
    "maxConcurrency": 100,
    "blockHistoryLimit": 300,
    "minConfirmations": 0
  },
  {
    "authorizers": {
      "requesterEndpointAuthorizers": []
    },
    "authorizations": {
      "requesterEndpointAuthorizations": {}
    },
    "contracts": {
      "AirnodeRrp": "0xa0AD79D995DdeeB18a14eAef56A549A04e3Aa1Bd"
    },
    "id": "3",
    "providers": {
      "infuraRopsten": {
        "url": "${CP_INFURA_ROPSTEN_URL}"
      }
    },
    "type": "evm",
    "options": {
      "fulfillmentGasLimit": 500000,
      "gasPriceOracle": [
        {
          "gasPriceStrategy": "latestBlockPercentileGasPrice",
          "percentile": 60,
          "minTransactionCount": 20,
          "pastToCompareInBlocks": 20,
          "maxDeviationMultiplier": 2
        },
        {
          "gasPriceStrategy": "providerRecommendedGasPrice",
          "recommendedGasPriceMultiplier": 1.2
        },
        {
          "gasPriceStrategy": "providerRecommendedEip1559GasPrice",
          "baseFeeMultiplier": 2,
          "priorityFee": {
            "value": 3.12,
            "unit": "gwei"
          }
        },
        {
          "gasPriceStrategy": "constantGasPrice",
          "gasPrice": {
            "value": 10,
            "unit": "gwei"
          }
        }
      ],
      "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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# authorizers

(required) - An object containing authorizers scheme types that contain authorizer contract addresses specifying the auth patterns that the AirnodeRrpV0 contract should use on-chain. Learn more about authorizers in Concepts and Build an Airnode.

# authorizations

(required) - An object containing authorizations scheme types that contain authorized endpointId/address pairs where the address is that of a requester. Airnode uses these pairs to determine access to its endpoints during its run cycle off-chain. Nothing in authorizers can supersede permissions granted by authorizations as they take precedence. Learn more about authorizations in Concepts and Build an Airnode.

# 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.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:if option.withdrawalRemainder present) - A number specifying the withdrawalRemainder value.

# options.withdrawalRemainder.unit

(required:if withdrawalRemainder present) - The unit of the withdrawalRemainder value. It can be one of the following: (wei, kwei, mwei, gwei, szabo, finney, ether).

# options.gasPriceOracle[n]

(required) - A list of gas price oracle strategies that the Airnode will use in the specified order. Each strategy has its own unique set of associated fields that describes it. See Gas Price Strategies for an in-depth understanding.

  • latestBlockPercentileGasPrice
    • percentile
      (required) - The percentile of gas prices to return from a block.
    • minTransactionCount
      (required) - The minimum amount of transactions required in a block to use for calculating a gas price percentile.
    • pastToCompareInBlocks
      (required) - The number of blocks to look back for the reference block.
    • maxDeviationMultiplier
      (required) - The maximum deviation multiplier of the latest block gas price percentile compared to the reference block gas price percentile. Used to protect against large gas price spikes.
  • providerRecommendedGasPrice
    • recommendedGasPriceMultiplier
      (required) - A number with a maximum of two decimals that gets multiplied by the provider reported gas price. The resulting Gas Price will equal Gas Price * providerRecommendedGasPrice.
  • providerRecommendedEip1559GasPrice
    • baseFeeMultiplier
      (required) - 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.
    • priorityFee:
      (required) - An object that configures the EIP-1559 Priority Fee. Defaults: {"value": 3.12, "unit": "gwei"}.
      • priorityFee.value
        (required) - A number specifying the EIP-1559 priority fee value.
      • priorityFee.unit
        (required) - The unit of the priority fee value. It can be one of the following: (wei, kwei, mwei, gwei, szabo, finney, ether).
  • constantGasPrice
    • gasPrice
      (required) - An object of the form {"value": 0, "unit": "wei"} that configures the amount to use as gas price.
      • gasPrice.value
        (required) - A number specifying the gasPrice value.
      • gasPrice.unit
        (required) The unit of the gasPrice 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.8.1",
  "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,
    "corsOrigins": []
  },
  "httpSignedDataGateway": {
    "enabled": true,
    "apiKey": "${HTTP_SIGNED_DATA_GATEWAY_API_KEY}",
    "maxConcurrency": 20,
    "corsOrigins": []
  },
  "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
31
32

# 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 to run Airnode as a docker container locally (client-image).

# cloudProvider.region

(required:if cloudProvider.type is AWS or 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:if cloudProvider.type is AWS or GCP) - Disables concurrency reservations for spawned cloud functions. For more information refer to the maxConcurrency section.

# cloudProvider.projectId

(required:if cloudProvider.type is GCP) - Project ID of the GCP project the Airnode will be deployed under.

# cloudProvider.gatewayServerPort

(optional:if cloudProvider.type is local) - The port number (defaults to 3000) of the API gateway inside the docker container. This property is especially useful, if the container is run using host networking (opens new window).

# 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

(required: if heartbeat.enabled is true) - The API key to authenticate against the heartbeat URL.

# heartbeat.id

(required: if heartbeat.enabled is true) - The Airnode heartbeat ID for accounting purposes.

# heartbeat.url

(required: if heartbeat.enabled is true) - 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

(required: if httpGateway.enabled is true) - 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

(required: if httpGateway.enabled is true) - 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.

# httpGateway.corsOrigins

(required: if httpGateway.enabled is true) - A list of allowed origins. An empty array ([]) can be used to disable CORS and the wildcard (['*']) can be used to allow all origins.

# 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

(required: if httpSignedDataGateway.enabled is true) - 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

(required: if httpSignedDataGateway.enabled is true) - 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.corsOrigins

(required: if httpSignedDataGateway.enabled is true) - A list of allowed origins. An empty array ([]) can be used to disable CORS and the wildcard (['*']) can be used to allow all origins.

# 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",
      "cacheResponses": false
    }
  ],
  "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
25

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.

# rrp[n].cacheResponses

(required) - Whether to cache API responses for an endpoint by requestId and return the cached response. Useful for non-idempotent API operations like random number generators.

# 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. The templates array must be included in the config.json file. The array 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.

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

# templateId

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

# endpointId

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

# encodedParameters

(required: for each row in templates) - 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: for each row in apiCredentials) - The ois.title of the OIS where the securitySchemeName can be found.

# securitySchemeName

(required: for each row in apiCredentials) - The name of a security scheme from ois[n].components.securitySchemes.{securitySchemeName}.

# securitySchemeValue

(required: for each row in apiCredentials) - 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 →