Environment variables

Configuration lives in one file: .env at the repository root, next to package.json. .env.example is the template the installer copies when no .env exists.

The backend loads it before any other module runs, probing four paths in order and stopping at the first that exists:

<cwd>/.env          # the repo root — this is the one you edit
<backend>/../.env
<backend>/.env
<cwd>/../.env

If none is found it falls back to the ambient process environment, which is how a container deployment can supply everything without a file at all.

The installer sets chmod 600 .env. Keep it that way — the file holds your database password, four session-signing secrets, every payment credential, and the passphrase that unlocks custodial wallet keys.

Editing it safely

pnpm env-manager is a targeted line editor for this file. It replaces one line at a time, so comments, section headers, ordering and quoting survive; a round-trip through a .env parser strips all of that.

node scripts/env-manager.mjs get --json
node scripts/env-manager.mjs set APP_TWILIO_AUTH_TOKEN=abc123 --restart

Every write snapshots a timestamped .env.bak and renames a temp file into place. With --restart it drains the backend, restarts, health-checks it, and rolls back to the snapshot if the process does not come back healthy. Secret-looking keys are redacted on read, so get reports set/unset rather than values.

The tool refuses to edit ENCRYPTED_ENCRYPTION_KEY and ENCRYPTION_KEY_PASSPHRASE at all. Changing either permanently bricks every encrypted wallet on the install.

Two rules that decide whether an edit takes effect

Everything else is read when a process starts. pnpm restart picks it up — pnpm stop && pnpm start, which parks the site on the maintenance server in between.

Application

Database

Sessions and token secrets

All four are 128-hex-character values. The installer generates them with crypto.randomBytes(64) on a fresh install. .env.example ships real-looking sample values — replace them.

There is no fallback and no default. Any secret that is unset or shorter than 32 characters makes the route that needs it fail with a 500 at the moment it is used, not at boot, so a bad APP_RESET_TOKEN_SECRET looks like "password reset is broken" rather than "the platform will not start".

Rate limiting

Redis

Redis is a hard boot dependency, not a cache. Sessions, CSRF tokens, rate-limit counters, distributed locks, the BullMQ scheduler and cross-process settings invalidation all live in it. The backend exits with code 78 (EX_CONFIG) when it is unreachable, printing the host and port it tried. Every PM2 config lists 78 in stop_exit_codes, so PM2 stops the app instead of crash-looping it.

sudo apt-get install -y redis-server && sudo systemctl enable --now redis-server
redis-cli -h 127.0.0.1 -p 6379 ping    # expects: PONG

Mail

SMS

Twilio delivers every SMS the platform sends: login and 2FA codes, phone verification, withdrawal and password-change codes, and notification messages. The provider refuses to initialise unless the account SID starts with AC and either a phone number or a messaging service SID is present.

Push notifications

Exchange providers

Which exchange is live is a database row set from Admin → Finance → Exchange Providers, not an environment variable. The backend then builds the credential names from the provider alias at runtime:

APP_${PROVIDER}_API_KEY
APP_${PROVIDER}_API_SECRET
APP_${PROVIDER}_API_PASSPHRASE

So a grep for APP_BINANCE_API_KEY in the source finds nothing even though the variable is load-bearing. Add the trio for whichever provider you activate.

Fiat exchange rates

Every configured provider is queried each run and the results are merged, so coverage is the union — a currency one source is missing is still priced by another. The keyless providers alone cover roughly 159 of 160 currencies.

Deposit gateways

Each gateway's readiness is computed from these variables, not from the database row — the credential names in backend/src/utils/deposit-gateway/registry.ts are read straight out of process.env, and Admin → Finance → Deposit → Gateways reports a gateway as unconfigured until they are present. All are optional: leave blank for any gateway you do not enable.

Stripe, PayPal, Paystack

TransFi (fiat on/off-ramp)

Sandbox and production credentials are not interchangeable: sandbox credentials return UNAUTHORIZED_CUSTOMER against api.transfi.com, and vice versa.

The other twelve gateways

Forex A-book execution

Hedge-execution venue credentials for the forex trading extension's A-book layer. These are not the market-data provider keys. All optional — leave blank for pure B-book operation.

AI services

Blockchain and the ecosystem extension

.env.example declares no RPC endpoint for any chain. A comment block describes the naming convention and stops there, so every endpoint the ecosystem extension needs has to be added by hand. Two things are exceptions. The explorer and transaction-provider keys further down are in the template, under Explorer / transaction-history providers. And custom EVM chains live in the ecosystem_custom_chain table, are managed from Admin → Ecosystem → Custom EVM Chains, and are written into process.env at boot from the database.

The naming convention is mechanical:

ETH_NETWORK="mainnet"
ETH_MAINNET_RPC="https://..."
ETH_MAINNET_RPC_WSS="wss://..."
ETH_EXPLORER_API_KEY="..."

# Optional, and worth setting: a second endpoint the chain falls back to.
ETH_MAINNET_RPC_FALLBACK="https://backup-1.example, https://backup-2.example"

<SYMBOL>_<NETWORK>_RPC accepts a comma-separated list, so you can also put several endpoints in the key you already have without learning a new one. Both keys are read and combined, in order, and duplicates are dropped.

Give every chain a second endpoint if you can. Deposits, withdrawals, balance reads and swap broadcasting all run through the same provider, so one rate-limited or briefly-down node takes all of them offline at once — and free-tier public endpoints rate-limit constantly. With more than one configured the platform orders them by measured latency, drops one that fails three times in a row, and brings it back on its own when it answers again. With exactly one it behaves as it always has. See the chain RPC runbook.

<SYMBOL>_NETWORK selects the network (default mainnet), and the code then reads <SYMBOL>_<NETWORK>_RPC and <SYMBOL>_<NETWORK>_RPC_WSS for that network. <SYMBOL>_EXPLORER_API_KEY is the per-chain Etherscan key, tried before ETHERSCAN_API_KEY rather than instead of it — the two lists are concatenated, so a stale per-chain key no longer shadows a working global one. The EVM symbols in use are ETH, BSC, POLYGON, FTM, OPTIMISM, ARBITRUM, CELO, BASE, RSK, plus MO.

UTXO chains take node connection details instead: <SYMBOL>_NODE_HOST (default 127.0.0.1), _NODE_PORT, _NODE_USER, _NODE_PASSWORD, and <SYMBOL>_MEMPOOL_API_URL. Non-EVM chains use their own families — TRON_NETWORK and TRON_API_KEY, SOL_NETWORK and SOLANA_RPC_URL, TON_NETWORK with TON_MAINNET_RPC and TON_MAINNET_RPC_API_KEY, XMR_DAEMON_RPC_URL (default http://127.0.0.1:18081/json_rpc) and XMR_WALLET_RPC_URL (default port 18083).

Explorer and transaction-history providers

Seven providers serve EVM transaction history and native-deposit detection, tried in a per-chain order with automatic failover. Two of them — Blockscout and Routescan — need no credential, and each is appended to the end of the order of every chain it can serve, so most chains work with none of these keys set. Five chains are the exception: BSC (56 and 97), Fantom (250 and 4002), Cronos (25), HECO (128 and 256) and Polygon Amoy (80002) have neither a hosted Blockscout instance nor Routescan coverage, so none of them gets a keyless provider appended to its order. BSC is the one where a keyed provider is the normal answer for a production install: NODEREAL_API_KEY is free for BSC mainnet, and on BSC testnet only MORALIS_API_KEY / COVALENT_API_KEY index it.

Every provider key, ETHERSCAN_API_KEY above included, may hold several comma-separated keys, rotated through on auth, plan and rate-limit failures, and every one has a chain-scoped form — BSC_NODEREAL_API_KEY, POLYGON_COVALENT_API_KEY — that is tried first with the global value behind it as a spare. The full per-chain picture is in the Ecosystem environment reference.

Master wallet encryption

Two variables unlock every custodial private key on the install. Neither is in .env.example. Generate them once, before creating any master wallet:

node scripts/kms/generate.mjs

It creates a 32-byte key, asks for a passphrase of at least 12 characters, and writes the AES-256-GCM result back to .env as four colon-separated hex parts (IV, auth tag, ciphertext, salt).

ScyllaDB

Ecosystem and futures order books, candles and trade tape live in ScyllaDB, not MySQL. The installer does not install it and .env.example declares none of these — the defaults below are what the code assumes when the variables are absent. Neither the built-in database backup nor mysqldump covers this data.

Licensing and product identity

Two-factor policy

The five withdrawTwoFactor* platform settings in Admin → System → Settings are the live controls. These three are the legacy fallbacks the login paths still read, and they are undeclared in .env.example.

KYC document storage

Other operational variables

None of these are in .env.example either, but several change behaviour you can observe.

Order admission and fail-fast

Everything in this group is off unless you set it, and with every variable unset the order path is byte for byte what it was before. Each one bounds a queue that a burst of bot orders could otherwise grow without limit, and refuses the request in front of it instead of letting it wait: a refusal written before the body is read costs the process a few tens of microseconds, where an order that queues for thirty seconds and then fails costs the process 8 to 9 milliseconds of CPU and stalls every other route on the way. The numbers quoted below were measured on the reference box (one backend process, tuned MariaDB, quiet): it accepts about 50 to 62 place-and-cancel pairs per second from bots (each pair is two requests through the gate), about 100 placements per second on an empty book, and one core is spent at 110 to 125 accepted requests per second. Your own figures come from the same probes, GET /api/admin/ecosystem/engine/health and the [ECO_ADMISSION] log line, both described in Monitoring.

Two doors take orders: the session door (/api/ecosystem/order*, the trading screen and the mobile app) and the signed Hummingbot door (/api/hb/order*). A refusal renders on each in the shape that door already uses. The session door answers HTTP 200 with {message, statusCode} in the body, as it does for every refusal today, plus a Retry-After header. The Hummingbot door answers a real status with {code, msg}: 429 as -1003, 503 as -1001. Nothing changes for a request that is accepted.

Unless an entry says otherwise the value is read on every request, so a change takes effect without a restart; pnpm env-manager set NAME=value --restart is still the safe way to write it.

The shed gate, before the body is read

One caller at a time

The wallet gate

These two sit beside WALLET_TX_CONCURRENCY and WALLET_QUEUE_TIMEOUT_MS above. The deadline refuses a write that has already waited thirty seconds; these refuse a hold, the write a new order takes on the wallet it spends, the moment it arrives at a queue that is already long, so a hundred thousand holds do not each arm a thirty-second timer and fail together late. Only holds are refused. A release, a cancel refund, a fee credit, a transfer, a settlement leg or an admin adjustment is never refused at entry, because a refund that was refused would leave the ledger different from today.

The matching engine and ScyllaDB

The engine flags, behind a canary

The variables in this subsection change how the matching engine does its work without changing what it writes: the same fills in the same sequence, the same ledger rows with the same keys and amounts, the same wire responses, with a flag on or off. Each one exists because a cost that used to grow with the depth of the book (a walk over every resting order per cycle, a pass over every market per placement, a reconciliation that held the engine lock across the whole book) was measured and replaced, and each one is off until you turn it on. They are read through one registry inside the backend, and four rules hold for all of them:

• Off by default. A backend with none of them set runs the engine it ran before they existed, byte for byte.
• Confined to a canary. ECO_ENGINE_CANARY_SYMBOLS names the markets a flagged behaviour may run on; empty means every market. Start with one quiet market and widen it.
• Money-affecting flags fail off. The flags marked money-affecting below read as off, without a restart, whenever the process cannot hear a kill: during boot until its settings-bus subscription lands, and whenever that Redis subscription is lost. The cost-only flags stay as configured, because losing one costs throughput, not rows. The registry also carries a kill switch on the settings-bus channel eco:scale:kill that turns every flag off in every process at once; in this release no admin screen or command publishes it, so the rollback you will actually use is to unset the variable and restart the process.
• Mirrors are proven or not trusted. The v2 book keeps second copies of the engine's resident orders; ECO_ENGINE_SELF_CHECK compares each copy against the original at every place the engine changes them, and a copy that diverges is reported before it can price anything.

All of them are read when the process starts, so change them with pnpm env-manager set NAME=value --restart. A flag reaching the engine is announced once in the log, per flag, with the lines quoted under each entry; scaleFlags on the engine health route shows every flag as configured (what the environment says) and effective (what the engine is doing right now), and both are described in Monitoring.

The order to turn them on is the order below, one at a time, on the trading process:

Cancel-all in batches

The ledger batcher

The shard tier

Everything in this block is off on a stock install, and an install that sets none of it runs the single matching engine of the sections above. Turning it on is a topology change, not a tuning knob: read Sharding the matching engine before setting any of them, because the ones that place a symbol on a shard have to agree across every process or two engines end up over one order book.

The Hummingbot limiter and key cache

Both belong with HB_RATE_LIMIT and HB_AUTH_FAIL_LIMIT under Rate limiting above, and ship with the Hummingbot Connector addon.

WebSocket ingress

These apply to every WebSocket route the backend registers, not only the market feed. The first four are handed to the socket server when a route is registered, so they need a restart; the last three are read per frame.

Ledger retention

The two ledger tables, transaction and wallet_audit_log, gain a row for every hold, release, fill leg and fee, and nothing removed one. These four variables drive a scheduled job on the cron process that moves old, finished rows into two archive tables with the same columns and hard-deletes them from the live ones. What moves, what never moves, how to run it by hand and how to put a row back are in Backup and restore. All four are read on every run.

Variables the code reads that the template never declares

Roughly two hundred variable names are read somewhere in backend/src and appear nowhere in .env.example. Most are tuning knobs with sane defaults. These are the ones that change whether something works:

Variables in the template that nothing reads

Setting any of these has no effect anywhere in the product. They are listed so you stop trying.

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID, NEXT_PUBLIC_FACEBOOK_PIXEL_ID and the googleAnalyticsStatus / facebookPixelStatus switches used to be on this list. They have been removed from the template and from Settings: no analytics or pixel script is loaded anywhere in the product, so there was nothing for them to switch on.