ArcPass Environment Variable Reference

ArcPass reads its entire configuration from environment variables at startup. There are no configuration files to edit — every behavior you need to change is controlled by setting the appropriate variable before launching the API or worker process. Copy .env.example from the repository root and fill in the required values before your first deployment.

Never commit SPONSOR_PRIVATE_KEY to version control. This key controls the relay operator account that holds and transfers gas funds on behalf of users. Treat it with the same care as a production wallet private key: store it in a secrets manager, CI secret, or encrypted vault — never in a .env file that is checked into a repository.

Database

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string for the ArcPass database. Example: `postgresql://user:password@localhost:5432/arcpass`

Blockchain and network

These variables are required by the worker process. The API does not connect to the blockchain directly.

Variable	Required	Default	Description
`CHAIN_RPC_URL`	Worker	—	RPC endpoint for the Arc network. The worker connects here to submit relay transactions and verify the chain ID at startup. `ARC_RPC_URL` is accepted as a legacy fallback.
`SPONSOR_PRIVATE_KEY`	Worker	—	Relay operator private key as 64 hex characters, with or without a `0x` prefix. This account signs and pays for on-chain relay transactions. `DEPLOYER_PRIVATE_KEY` is accepted as a legacy fallback.
`CHAIN_ID`	Worker	—	Chain ID of the target network. The worker checks this against the connected RPC endpoint at startup and exits if there is a mismatch. For the Arc testnet, use `5042002`.
`CONTRACT_ADDRESS_SPONSOR_VAULT`	Worker	—	Deployed address of the `SponsorVault` contract, which holds the gas treasury and executes authorized transfers.
`CONTRACT_ADDRESS_SPONSORSHIP_REGISTRY`	Worker	—	Deployed address of the `SponsorshipRegistry` contract, which records on-chain sponsorship accounting.

Sponsorship

Variable	Required	Default	Description
`SPONSORSHIP_AMOUNT_WEI`	No	`1000000000000000`	Amount of native tokens to transfer per sponsorship, expressed in wei. The default is 0.001 tokens (1,000,000,000,000,000 wei).

API

Variable	Required	Default	Description
`PORT`	No	`4000`	TCP port the Fastify API listens on.
`LOG_LEVEL`	No	`info`	Pino log verbosity. Accepted values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`.
`CORS_ALLOWED_ORIGINS`	No	—	Comma-separated list of origins the API accepts cross-origin requests from. When unset, CORS is not restricted. Example: `https://app.example.com,https://staging.example.com`

Worker tuning

These variables control how aggressively the worker polls for work and how it handles timeouts and retries. The defaults are suitable for most deployments.

Variable	Required	Default	Description
`POLL_INTERVAL_MS`	No	`5000`	How often (in milliseconds) the worker checks for pending and stale sponsorship requests to process.
`BATCH_SIZE`	No	`20`	Maximum number of sponsorship requests the worker processes in a single cycle.
`MAX_RETRIES`	No	`5`	Maximum number of times the worker retries a failed relay attempt before marking the request as permanently failed.
`LOCK_TIMEOUT_MS`	No	`30000`	Timeout in milliseconds for the internal processing transaction per sponsorship request.
`TX_TIMEOUT_MS`	No	`120000`	Timeout in milliseconds for waiting on an on-chain transaction receipt after the relay transaction is broadcast.
`CONFIRMATION_BLOCKS`	No	`2`	Number of block confirmations to wait for before treating a relay transaction as finalized.

Rate limiting

Variable	Required	Default	Description
`RATE_LIMIT_IP_MAX`	No	`10`	Maximum number of sponsorship requests allowed from a single IP address within the rate limit window.
`RATE_LIMIT_WALLET_MAX`	No	`5`	Maximum number of sponsorship requests allowed from a single wallet address within the rate limit window.
`RATE_LIMIT_WINDOW_MS`	No	`3600000`	Duration of the rate limit sliding window in milliseconds. The default is one hour (3,600,000 ms).
`RATE_LIMIT_BLOCK_DURATION_MS`	No	`900000`	How long (in milliseconds) an IP or wallet is automatically blocked after exceeding the rate limit threshold. The default is 15 minutes (900,000 ms).

Get Started

Using ArcPass

Core Concepts

Configuration

FAQ

ArcPass Environment Variable Reference

Database

Blockchain and network

Sponsorship

API

Worker tuning

Rate limiting

​Database

​Blockchain and network

​Sponsorship

​API

​Worker tuning

​Rate limiting

Database

Blockchain and network

Sponsorship

API

Worker tuning

Rate limiting