Settings

The settings section configures global behavior. It is placed immediately after version and server, before apis.

settings:
  timeout: 10000 # default, ms
  maxConcurrentApiCalls: 50
  proof: none
  fhe: none
  plugins:
    - source: ./plugins/heartbeat.ts
      timeout: 5000

Fields

Field	Type	Required	Default	Description
timeout	number	No	10000	Global upstream API request timeout in milliseconds.
maxConcurrentApiCalls	number	Yes	--	Process-wide ceiling on concurrent upstream API calls.
proof	string | object	No	'none'	Proof mode. See Proof.
fhe	string | object	No	'none'	FHE encryption relayer. See FHE.
plugins	array	No	[]	Plugin entries. See Plugin Configuration.

timeout

Default timeout for upstream API requests in milliseconds. This applies to all APIs unless overridden at the API level with apis[].timeout.

settings:
  timeout: 15000 # 15 seconds for all APIs by default

maxConcurrentApiCalls

A process-wide cap on how many upstream API calls can be in flight at once, across all requests. A burst of requests can't fan out more fetches than this to your (metered) APIs. When the cap is reached, a request waits for a slot up to the relevant API's timeout, then gives up with 503 Server busy. The per-IP server.rateLimit bounds the inflow; this bounds the fan-out to upstreams.

settings:
  maxConcurrentApiCalls: 100

proof

Controls whether TLS proofs are attached to responses. Two modes are supported:

No proof (default)

settings:
  proof: none

Responses contain only the EIP-191 signature. No proof is generated.

Reclaim TLS proof

settings:
  proof:
    type: reclaim
    gatewayUrl: http://localhost:5177/v1/prove

Field	Type	Required	Description
type	string	Yes	Must be 'reclaim'.
gatewayUrl	string	Yes	Full URL of the proof gateway endpoint. Must be a valid URL.
timeout	number	No (default 30000)	Gateway request timeout in milliseconds. The proof is fetched after signing on the sync path, so this latency is added to the response; a timeout just omits the proof field.

When enabled, Airnode requests a TLS proof from the gateway after each API call. The proof is attached to the response in a proof field alongside the signature. See TLS Proofs for details on how proofs work.

Important: gatewayUrl must be the full URL to the proof endpoint (e.g., http://localhost:5177/v1/prove), not just a base URL. Airnode sends the request directly to this URL.

Proof generation is non-fatal. If the proof gateway is unavailable or returns an error, the response is still returned without the proof field and a warning is logged. This ensures proof failures do not block data delivery.

Endpoints must have responseMatches configured for proof generation to be requested. Endpoints without responseMatches skip proof generation even when proof is enabled globally.

fhe

Configures FHE encryption of encoded responses. When set to an object, any endpoint with an encrypt block has its ABI-encoded value replaced with an FHE ciphertext before signing.

No FHE (default)

settings:
  fhe: none

Zama relayer

settings:
  fhe:
    network: sepolia
    rpcUrl: ${FHE_RPC_URL}
    verifier: '0x...' # AirnodeVerifier on the fhEVM chain
    # apiKey: ${FHE_API_KEY}  # optional

Field	Type	Required	Description
network	string	Yes	'sepolia' or 'mainnet' — selects the Zama chain preset (contract addresses, chain IDs, relayer URL).
rpcUrl	string	Yes	Ethereum JSON-RPC endpoint for that chain. Must be a valid URL.
verifier	string	Yes	AirnodeVerifier contract address on that chain. The encrypted input is bound to it — see FHE Encryption.
apiKey	string	No	API key for Zama's hosted relayer (not required for Sepolia testnet).

If any endpoint has an encrypt block, settings.fhe must be configured — validation fails otherwise. See FHE Encryption for the full flow and consumer-contract requirements.

plugins

An array of plugin entries. Each entry specifies a source file and a timeout budget. When omitted or empty, no plugins are loaded.

settings:
  plugins:
    - source: ./plugins/heartbeat.ts
      timeout: 5000
    - source: ./plugins/slack-alerts.ts
      timeout: 3000

See Plugin Configuration for details on source resolution, timeout budgets, and ordering.