> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madra.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Every environment variable and config key StellarX402 accepts, grouped by subsystem.

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. |

## Sponsor account

| 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](/guides/operators/security-hardening) for how to set these safely.