.env.example

# Stellar Network Configuration
# One of: mainnet | testnet | futurenet
NEXT_PUBLIC_STELLAR_NETWORK=mainnet_or_testnet

# Horizon API URL
# Mainnet: https://horizon.stellar.org
# Testnet: https://horizon-testnet.stellar.org
NEXT_PUBLIC_HORIZON_URL=https://horizon.stellar.org_or_testnet_url

# USDC Issuer Account Address on Stellar Network
# This is the trusted issuer for USDC tokens
NEXT_PUBLIC_USDC_ISSUER=stellar_public_key_here

# Application Name (required — boot fails if unset)
NEXT_PUBLIC_APP_NAME="App_Name_Here"

# Stellar Expert API base for transaction links (optional)
# Default: https://api.stellar.expert/explorer/public
NEXT_PUBLIC_STELLAR_EXPERT_URL=https://api.stellar.expert/explorer/public

# Canonical site URL used for <meta og:url>, <link rel="canonical">, sitemap, and robots.txt.
# When unset, every canonical and OG tag resolves to the Vercel deployment URL
# (https://stellar-intel.vercel.app or the current preview URL) rather than your
# custom domain. Set this to your production domain in Vercel project settings.
# NEXT_PUBLIC_SITE_URL=https://your-domain.com

# ─── Feature flags ────────────────────────────────────────────────────────────
# All flags are baked into the client bundle at build time (NEXT_PUBLIC_* prefix).
# On/off semantics differ per flag; read the per-flag comment.

# Feature flag — signed-intent off-ramp path is OFF unless set to "true"
NEXT_PUBLIC_INTENT_FLOW=false

# Reputation writes: submitting outcomes after a completed off-ramp is ON by
# default. Set to 'off' to disable without a redeploy.
# NEXT_PUBLIC_REPUTATION_WRITES=off

# MCP advertisement: surfacing the MCP install banner in the UI is ON by
# default. Set to 'off' to hide it.
# NEXT_PUBLIC_MCP_ADVERTISE=off

# v1.1 corridors (ZAR, XOF): OFF by default until anchors are onboarded.
# Even when 'on', a corridor stays hidden until at least one anchor serves it.
# NEXT_PUBLIC_V11_CORRIDORS=on

# Recurring intents (sign-once execution engine): OFF by default. Gated behind
# NEXT_PUBLIC_INTENT_FLOW — enabling this while INTENT_FLOW is off has no effect.
# NEXT_PUBLIC_RECURRING_INTENTS=on

# Admin secret key — required to access /admin/disputes and related API routes
ADMIN_SECRET_KEY=your_secret_admin_key_here

# ─── Webhooks (#822) ──────────────────────────────────────────────────────────

# Webhook subscriptions are managed via POST /api/webhooks/subscriptions (admin key required).
# Per-subscription HMAC secrets are generated at creation time and stored in the webhook store.
# No additional environment variables are required for basic operation.

# ─── Server-side (optional) ───────────────────────────────────────────────────

# Router selection strategy: "first-match" (default) or "scored" (multi-factor solver).
# Keep on first-match until the scored strategy is validated in staging.
ROUTING_STRATEGY=first-match

# Max acceptable fee as a fraction of the amount, e.g. 0.05 for 5% (router budget)
FEE_BUDGET_PCT=0.05

# Soroswap aggregator API key (https://api.soroswap.finance), required by the
# swap hop connector (lib/router/connectors/swap-soroswap.ts). Unset fails
# loudly (#1086): getSoroswapQuote/buildSoroswapTransaction throw
# SoroswapConfigError naming SOROSWAP_API_KEY before any request is sent,
# rather than the swap hop silently skipping itself.
SOROSWAP_API_KEY=your_soroswap_api_key_here

# Soroswap API base URL (default: https://api.soroswap.finance). Override only
# when pointing at a local Soroswap instance during development or testing.
# SOROSWAP_API_BASE_URL=https://api.soroswap.finance

# Destination accounts for the signed-intent off-ramp path, as JSON mapping an
# anchor id from constants/anchors.ts to a Stellar account.
#
# REQUIRED for /api/intent/offramp to route anything. Unset means every corridor
# returns NO_ROUTE, which is deliberate: this replaced two hardcoded addresses
# that did not exist on mainnet, so the endpoint handed out payments that could
# only fail (#941).
#
# Verify every address against Horizon before adding it. A typo here is a
# payment to a stranger. Note that most SEP-24 anchors issue a destination
# through their interactive flow rather than publishing a static one, so there
# may be no correct value for a given anchor.
#
# ANCHOR_PAYMENT_ACCOUNTS='{"cowrie":"GABC...","moneygram":"GDEF..."}'

# Shared secret required by cron-triggered routes (publisher tick / reconcile / refresh)
CRON_SECRET=your_cron_secret_here

# Reputation store backend: "sqlite" (default) or "postgres"
# Setting DATABASE_URL implies the postgres backend.
REPUTATION_BACKEND=sqlite
DATABASE_URL=postgres://user:pass@host:5432/dbname

# Pino log level: trace | debug | info | warn | error (default: info)
LOG_LEVEL=info

# Metrics rolling-window length in milliseconds (default: 3600000 = 1h)
METRICS_RESET_WINDOW_MS=3600000

# ─── Reputation thresholds (optional) ────────────────────────────────────────

# Minimum number of recorded outcomes before a reputation score is considered
# statistically meaningful. Anchors below this count show as "insufficient data"
# rather than a calculated score. Default: 30.
# NEXT_PUBLIC_MIN_OUTCOMES=30

# Maximum quote deviation from the cross-anchor median for the same corridor and
# amount, expressed as a percentage, before the drift probe flags the anchor.
# Flagging is informational — a drifted anchor is never auto-excluded. Default: 3.
# QUOTE_DRIFT_THRESHOLD_PERCENT=3

# Consecutive failing probe cycles before an anchor is marked 'degraded'. Shared
# with the nightly auto-degrade validator (scripts/validate-anchors.mjs) so the
# live probe and the ledger debounce on the same threshold. Default: 3.
# ANCHOR_DEGRADE_THRESHOLD=3

# Consecutive failing probe cycles before a degraded anchor is escalated to
# 'down'. Floored at ANCHOR_DEGRADE_THRESHOLD so it can never be easier to reach
# 'down' than 'degraded'. Default: twice ANCHOR_DEGRADE_THRESHOLD (i.e. 6).
# ANCHOR_DOWN_THRESHOLD=6

# Maximum tolerated quote latency in milliseconds. A reachable anchor that is
# slower than this budget counts as a latency-dimension probe failure. Default: 5000.
# PROBE_LATENCY_BUDGET_MS=5000

# ─── Soroban oracle ops scripts ───────────────────────────────────────────────

# Soroban reputation oracle contract address — required by scripts/init-oracle-registry.ts
# and by the publisher (CLI and /api/publisher/tick).
ORACLE_CONTRACT_ID=your_contract_id_here

# Which network the publisher signs against. REQUIRED by the publisher CLI, and
# deliberately has no default: it signs real transactions, and an unset value
# used to mean mainnet (#912). One of: mainnet | testnet
STELLAR_NETWORK=testnet

# Secret key of an account registered as a publisher on the oracle contract.
# Required by both the publisher CLI and /api/publisher/tick — without it the
# tick throws. Keep this out of shell history and out of the repo.
PUBLISHER_SECRET=S...

# Optional endpoint overrides. Both default from STELLAR_NETWORK; set them only
# for a custom RPC or a local quickstart. Note the network passphrase always
# follows STELLAR_NETWORK and cannot be overridden on its own — overriding the
# passphrase alone is how a testnet key ends up signing on mainnet.
# SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# HORIZON_URL=https://horizon-testnet.stellar.org

# Network passphrase override for Soroban oracle reads (lib/oracle/read.ts).
# Defaults from STELLAR_NETWORK. Override only when targeting a custom or local
# network, and only in combination with a matching SOROBAN_RPC_URL.
# STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# Rows per publisher batch (default: see DEFAULT_BATCH_SIZE in packages/publisher).
# BATCH_SIZE=25

# Bypasses the 90-day probe-coverage gate on a mainnet publish (#786). Testnet
# is never gated, so this does nothing there. Compared against the exact string
# "true" — PUBLISH_GATE_OVERRIDE=false leaves the gate ON, as it reads.
# Every override logs at error level; there is no quiet way to use it.
# PUBLISH_GATE_OVERRIDE=true

# Deployer key for scripts/deploy-oracle-mainnet.ts. Only needed for a mainnet
# deploy; leave unset otherwise.
# MAINNET_DEPLOYER_KEY=S...

# Server-side rate fetch timeouts (milliseconds) and retries per tier.
# Leave unset to use the built-in defaults (8s timeout, 1 retry on network errors only).
# RATES_TOML_TIMEOUT_MS=8000
# RATES_SEP38_TIMEOUT_MS=8000
# RATES_SEP24_INFO_TIMEOUT_MS=8000
# RATES_TOML_RETRY_ATTEMPTS=1
# RATES_SEP38_RETRY_ATTEMPTS=1
# RATES_SEP24_INFO_RETRY_ATTEMPTS=1

# ─── Analytics (optional) ────────────────────────────────────────────────────

# Plausible Analytics domain. Leave unset in dev to prevent tracking; set it
# to the deployed domain in production only. When unset, no script is injected
# and lib/analytics.ts no-ops.
# NEXT_PUBLIC_PLAUSIBLE_DOMAIN=stellar-intel.vercel.app

# ─── Test environment only (not for production use) ──────────────────────────

# When set in NODE_ENV=test, enables real SEP-24 /info requests instead of
# returning mock data. Has no effect outside of test runs. Unset means the
# test suite skips the live /info call.
# TEST_SEP24_INFO=true