Configuring ENSApi

ENSApi’s behavior can be configured through environment variables. Copy .env.local.example to .env.local and configure all required values.
# The port ENSApi listens on.
# Optional. If this is not set, the default value is 4334.
# PORT=4334

# ENSIndexer: The "primary" ENSIndexer service URL.
# Required. This URL is used to read ENSIndexer's Config and Indexing Status APIs.
ENSINDEXER_URL=http://localhost:42069

# ENSDb: Database URL
# Required. This is the connection string for the ENSDb database in which ENSIndexer is storing data.
# It should match the DATABASE_URL used by the connected ENSIndexer.
# It should be in the format of `postgresql://<username>:<password>@<host>:<port>/<database>`
#
# See https://ensnode.io/ensindexer/usage/configuration/ for additional information.
# NOTE that ENSApi does NOT need to define DATABASE_SCHEMA, as it is inferred from the connected ENSIndexer's Config.
DATABASE_URL=postgresql://dbuser:abcd1234@localhost:5432/my_database

# ENSApi: RPC Configuration
# Required. ENSApi requires an HTTP RPC to the connected ENSIndexer's ENS Root Chain, which depends
# on ENSIndexer's NAMESPACE (ex: mainnet, sepolia, holesky, ens-test-env). This ENS Root Chain RPC
# is used to power the Resolution API, in situations where Protocol Acceleration is not possible.
#
# When ENSApi starts up it connects to the indicated ENSINDEXER_URL verifies that the ENS Root Chain
# RPC for the specified namespace is defined.
#
# NOTE: You must configure your own private RPC endpoints. Public RPC endpoints are rate limited and
# will likely not provide acceptable performance (though this depends on how many non-acceleratable
# Resolution requests you make to ENSApi).
#
# Private RPC service options include:
# - Alchemy (paid plan) - https://www.alchemy.com/
# - QuickNode (paid plan) - https://www.quicknode.com
# - drpc.org (paid plan) - https://drpc.org/
# - Infura (paid plan) - https://infura.io/
#
# Example RPC endpoint URL formats:
# - Alchemy RPC endpoints
#   - https://eth-mainnet.g.alchemy.com/v2/<alchemy-api-key>
#   - wss://eth-mainnet.g.alchemy.com/v2/<alchemy-api-key>
#   - https://base-sepolia.g.alchemy.com/v2/<alchemy-api-key>
# - QuickNode RPC endpoints
#   - https://<quicknode-endpoint-name>.quiknode.pro/<quicknode-api-key>
#   - wss://<quicknode-endpoint-name>.quiknode.pro/<quicknode-api-key>
#   - https://<quicknode-endpoint-name>.base-sepolia.quiknode.pro/<quicknode-api-key>
# - dRPC RPC endpoints
#   - https://lb.drpc.live/ethereum/<drpc-api-key>
#   - wss://lb.drpc.live/ethereum/<drpc-api-key>
#   - https://lb.drpc.live/base-sepolia/<drpc-api-key>
# - Infura RPC endpoints
#   - https://mainnet.infura.io/v3/<infura-api-key>
#   - wss://mainnet.infura.io/ws/v3/<infura-api-key>
#   - https://base-sepolia.infura.io/v3/<infura-api-key>
#
# Configuring the following environment variables enables auto-generation of
# RPC endpoint URLs for each indexed chain (with limitations as noted below):
# - ALCHEMY_API_KEY — API key for your Alchemy app, if set, Alchemy RPC URLs (HTTP) will be autogenerated for chains Alchemy supports.
# - QUICKNODE_API_KEY - API key for your multi-chain QuickNode endpoint.
# - QUICKNODE_ENDPOINT_NAME — endpoint name of your multi-chain QuickNode endpoint.
# - DRPC_API_KEY — if set, an dRPC RPC URL (HTTP) will be autogenerated for chains dRPC supports.
# - RPC_URL_${chainId} — specific, per-chain RPC settings.
#
# If both, QUICKNODE_API_KEY and QUICKNODE_ENDPOINT_NAME are specified,
# a QuickNode RPC URL will be autogenerated for chains QuickNode supports.
# If only one of QUICKNODE_API_KEY or QUICKNODE_ENDPOINT_NAME is set but not the other,
# the configuration will be rejected with an error.
# Note key constraints of QuickNode RPC endpoints:
#   - Only multi-chain QuickNode endpoints can be used for setting
#     QUICKNODE_API_KEY and QUICKNODE_ENDPOINT_NAME environment variables.
#     A multi-chain endpoint allows sharing the same endpoint name and API key
#     across all chains supported by QuickNode platform. Read more in QuickNode docs:
#     https://www.quicknode.com/guides/quicknode-products/how-to-use-multichain-endpoint
#   - QuickNode platform does not support Linea Sepolia RPC (as of 2025-12-03).
#     https://www.quicknode.com/docs/linea
#
# Each RPC_URL_${chainId} environment variable, if specified, will take precedence over
# all auto-generated RPC URLs for the specified chainId from Alchemy, QuickNode, or dRPC.
# It must be a comma-separated list of HTTP/HTTPS RPC endpoints.
# ENSApi provides all the resulting RPC URLs to Viem Client. If multiple HTTP RPC URLs are provided to Viem Client,
# Viem Client automatically balances requests between them (see below).
#
# Auto-generated RPC URLs:
# ALCHEMY_API_KEY=xyz
# QUICKNODE_API_KEY=your-api-key
# QUICKNODE_ENDPOINT_NAME=your-endpoint-name
# DRPC_API_KEY=xyz
#
# For full control of chain-specific RPC configuration, use the RPC_URL_{chainId} environment variable.
# Its value is a comma-separated list of one or more HTTP RPC URLs.
#
# Example (single HTTP RPC URL):
# RPC_URL_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
#
# Example (multiple HTTP RPC URL, single WebSocket RPC URL):
# RPC_URL_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY,https://lb.drpc.org/ethereum/YOUR_API_KEY
#
# The RPC_URL_${chainId} value has the following invariants:
# - Must always include at least one HTTP/HTTPS RPC endpoint. RPC endpoints can
#   fail or experience downtime. To optimize resiliency of ENSIndexer,
#   defining more than one HTTP/HTTPS endpoint (from more than one RPC provider)
#   per indexed chain is strongly encouraged.

# Log Level
# Optional. If this is not set, the default value is "info".
# Allowed values: "fatal", "error", "warn", "info", "debug", "trace", "silent".
# LOG_LEVEL=info

# The Graph Subgraph API Fallback
# Optional. If this value is set, on the condition that the connected ENSIndexer is not
# sufficiently "realtime", ENSApi's Subgraph API will fallback to proxying subgraph queries
# it receives to The Graph's hosted subgraphs using this API key.
# THEGRAPH_API_KEY=

# ENS Holiday Awards Date Range
# Optional. These variables define the date range for ENSAnalytics ENS Holiday Awards campaign.
# If not set, defaults to the hardcoded values from @namehash/ens-referrals package.
# Format: ISO 8601 datetime string (e.g., "2025-12-01T00:00:00Z")
# Note: ENS_HOLIDAY_AWARDS_START date must be before or the same as ENS_HOLIDAY_AWARDS_END
# ENS_HOLIDAY_AWARDS_START="2025-12-01T00:00:00Z"
# ENS_HOLIDAY_AWARDS_END="2025-12-31T23:59:59Z"
.env.local.example View this file on GitHub.