Configuration

Comet Engine is configured via environment variables (with .env support for local development).

Core

Variable	Default	Description
PORT	8100	HTTP listen port
MONGO_URI	mongodb://localhost:27017	MongoDB connection string
MONGO_DB	comet_engine	MongoDB database name

Authentication

Variable	Default	Description
SERVICE_TOKENS	(empty)	Comma-separated allowlist of X-Service-Token values
WALLET_ENCRYPTION_KEY	(empty)	CRITICAL — Master secret for AES-GCM sealing of user EVM private keys. Losing this loses every wallet.

Chain Configuration

Assets are auto-discovered from env vars using the pattern {CHAIN}_{SYMBOL}_CONTRACT.

Per-Chain Variables

Variable	Required	Description
{CHAIN}_RPC_URL	Yes	JSON-RPC endpoint
{CHAIN}_CHAIN_ID	Yes	EVM chain ID
{CHAIN}_RELAYER_PRIVATE_KEY	Yes	Platform relayer private key (hex)
{CHAIN}_UNISWAP_FACTORY	No	UniswapV2Factory address
{CHAIN}_UNISWAP_ROUTER	No	UniswapV2Router02 address
{CHAIN}_{SYMBOL}_CONTRACT	No	ERC-20 contract address
{CHAIN}_{SYMBOL}_TYPE	No	Asset type (utility, stablecoin, airtime)
{CHAIN}_{SYMBOL}_BACKING	No	Backing type (none, fiat-reserve, airtime)

Adding a New Asset

Deploy the contract and set the env var. No code changes needed:

CELO_MYTOKEN_CONTRACT=0x...
CELO_MYTOKEN_DECIMALS=18

Adding a New Chain

CUSTOM_CHAINS=base
BASE_RPC_URL=https://mainnet.base.org
BASE_CHAIN_ID=8453
BASE_RELAYER_PRIVATE_KEY=0x...

Chain Selection

Select chain via ?chain= query parameter. Defaults to the first configured chain (typically celo).

POST /api/v1/assets/USDT/mint?chain=celo
POST /api/v1/assets/USDT/mint?chain=base

Stellar Chain

Set STELLAR_RELAYER_SEED to enable a separate, non-EVM wallet family (see Wallets API →). Absent this variable, chain=stellar requests return 400 chain "stellar" not configured — every other chain and endpoint is unaffected.

Variable	Default	Description
STELLAR_RELAYER_SEED	(empty)	Required to enable Stellar. Secret seed (S...) of the relayer/issuer account — pays fees, funds every new user wallet on creation, and in phase 1 issues assets registered on this chain. This account must already be funded on-chain before Stellar wallets will work — an unfunded relayer fails wallet creation with stellar: relayer account ... is not funded.
STELLAR_HORIZON_URL	https://horizon-testnet.stellar.org	Horizon API endpoint
STELLAR_NETWORK_PASSPHRASE	Test SDF Network ; September 2015	Network passphrase (use the mainnet phrase in production)
STELLAR_BLOCK_EXPLORER	https://stellar.expert/explorer/testnet	Explorer base URL used in responses/UIs

Stellar assets are auto-discovered the same way EVM assets are, using the STELLAR_{SYMBOL}_CONTRACT-style pattern (asset issuer address, not a contract address).

Full setup walkthrough (generating and funding the relayer keypair) is in Setting Up Stellar →.

Every functionality this touches

Once configured, ?chain=stellar (or "chain": "stellar") works on: Create/Get Wallet, Wallet Balance, Token Balance, Mint, Send, Burn (Holder), and Register/Deregister Asset. It does not apply to Approve or Burn (Relayer) — Stellar has no allowance concept, both return 501 — or to AMM swaps/pools, which are Celo/Uniswap-specific and have no chain parameter at all.

PSP / Mobile Money Top-up

Set these to enable the PSP top-up admin endpoints (POST /api/v1/admin/topup/stk-push, /api/v1/admin/topup/transfer) and their callback receiver. Absent PSP_API_KEY/PSP_API_SECRET, those endpoints return 503 PSP integration not configured.

Variable	Default	Description
PSP_BASE_URL	https://payments.mamlakapsp.com	PSP API base URL
PSP_MERCHANT_ID	(empty)	Merchant ID issued by the PSP
PSP_API_KEY	(empty)	Required to enable PSP top-up.
PSP_API_SECRET	(empty)	Required to enable PSP top-up.
PSP_CALLBACK_SECRET	(empty)	Shared secret used to verify the X-Mamlaka-Signature header on incoming callbacks
PSP_CALLBACK_BASE_URL	(empty)	This engine's own publicly-reachable base URL, used to build the callback URL sent to the PSP on each top-up/transfer request

Asset Type & Backing

Type	Backing	Description
utility	none	Standard token (USDT, USDC)
airtime	airtime	Backed by real airtime float (IMC)

Airtime-backed assets use special journaling: mints debit the airtime inventory account, burns credit it. This keeps on-chain supply pegged to real float.

Cardano Proxy

Variable	Default	Description
CARDANO_RPC_URL	(empty)	External Cardano proxy service URL
CARDANO_SERVICE_TOKEN	(empty)	Bearer token for the Cardano proxy