Configuration Reference - StellarX402

All configuration is via environment variables or a JSON/TOML file passed with --config. Env vars win on conflict.

Server

Key	Type	Default	Purpose
`PORT`	int	`4020`	HTTP listen port.
`HOST`	string	`0.0.0.0`	Bind address.
`LOG_LEVEL`	string	`info`	`trace` \| `debug` \| `info` \| `warn` \| `error`.
`TRUST_PROXY`	bool	`false`	Trust `X-Forwarded-*` headers. Set `true` behind a load balancer.

Network

Key	Type	Default	Purpose
`NETWORK`	string	—	`stellar:testnet` or `stellar:pubnet`. Required.
`STELLAR_RPC_URL`	string	—	Soroban RPC endpoint. Required.
`STELLAR_RPC_FALLBACK_URLS`	csv	—	Additional RPCs, tried in order on primary failure.

Key	Type	Default	Purpose
`SPONSOR_SECRET_KEY`	string	—	Stellar secret for the fee-sponsoring account. Required.
`SPONSOR_FEE_CEILING_XLM`	decimal	`0.1`	Per-tx fee ceiling in XLM.
`SPONSOR_MIN_BALANCE_XLM`	decimal	`5`	Alert threshold.
`SPONSOR_ALERT_WEBHOOK`	url	—	POSTed when balance dips below `SPONSOR_MIN_BALANCE_XLM`.

Assets

Key	Type	Default	Purpose
`ALLOWED_ASSETS`	csv	`USDC`	Whitelist of accepted SEP-41 assets.
`ASSET_OVERRIDES`	json	—	Override contract addresses per asset symbol.

Discovery (Bazaar)

Key	Type	Default	Purpose
`DISCOVERY_ENABLED`	bool	`true`	Turn the Bazaar off entirely.
`DISCOVERY_STORAGE`	url	`sqlite:./bazaar.db`	`postgres://...` or `sqlite:...`.
`DISCOVERY_DELIST_AFTER_HOURS`	int	`24`	Consecutive-failure delist window.
`DISCOVERY_DUPLICATE_THRESHOLD`	float	`0.9`	Similarity above which listings merge.
`DISCOVERY_MIN_SETTLE_RATIO`	float	`0.1`	Rank penalty threshold.

Observability

Key	Type	Default	Purpose
`METRICS_ENABLED`	bool	`true`	Exposes `/metrics` in Prometheus format.
`METRICS_PORT`	int	`9090`	Metrics scrape port (separate from `PORT`).
`OTEL_EXPORTER_OTLP_ENDPOINT`	url	—	OpenTelemetry OTLP endpoint.

Security

Key	Type	Default	Purpose
`RATE_LIMIT_RPM`	int	`600`	Requests per minute per IP.
`ALLOWED_ORIGINS`	csv	`*`	CORS allowlist.
`ADMIN_TOKEN_HASH`	string	—	Bcrypt of admin bearer. Required for admin endpoints.

See Security Hardening for how to set these safely.