.env.example

# ============================================================================
# STELLAR NETWORK CONFIGURATION
# ============================================================================
# Read more: https://developers.stellar.org/docs/learn/networks
#
# STELLAR_NETWORK - Which Stellar network to connect to. This determines:
#   • Which Horizon server is used to fetch blockchain data
#   • Whether testnet-only endpoints (like Friendbot) are available
#   • Account balances, transaction history, and asset metadata
#
# IMPORTANT: Do NOT confuse STELLAR_NETWORK with the network passphrase.
# This variable controls which PUBLIC network you connect to.
#
# Available values: "testnet" or "mainnet"
#
# TESTNET: "Test SDF Network ; September 2015"
#   • Free, experimental network for development and testing
#   • Account balances and transactions reset periodically
#   • Friendbot endpoint available to fund test accounts
#   • Connect via: https://horizon-testnet.stellar.org
#   • Use this for development, QA, and feature testing
#   • NEVER use real money or production private keys on testnet
#
# MAINNET: "Public Global Stellar Network ; September 2015"
#   • Production network where real transactions and value occur
#   • Data is persistent; accounts and balances never reset
#   • Friendbot is NOT available (use real funds to create accounts)
#   • Connect via: https://horizon.stellar.org
#   • Use only when deployed to production
#   • ALWAYS use with secure key management and proper monitoring
#
# ⚠️  CRITICAL: Set this to "mainnet" explicitly before production deployment.
#    Leaving this as "testnet" in production will use test data and may block
#    real transactions from being signed or submitted.
#
STELLAR_NETWORK=testnet

# ============================================================================
# HORIZON SERVER URL (Optional Override)
# ============================================================================
# Read more: https://developers.stellar.org/docs/data/apis/horizon
#
# HORIZON_URL - Override the Horizon API endpoint. When left empty, the server
# automatically selects the correct public Horizon server based on STELLAR_NETWORK.
#
# Leave this blank in most cases unless you need to:
#   • Use a private/custom Horizon instance
#   • Point to a load balancer or proxy
#   • Connect to a staging or development Horizon server
#
# Default behavior (when HORIZON_URL is empty):
#   • If STELLAR_NETWORK=testnet  → uses https://horizon-testnet.stellar.org
#   • If STELLAR_NETWORK=mainnet  → uses https://horizon.stellar.org
#
# Horizon is the REST API layer that allows this application to:
#   • Query account balances and transaction history
#   • Stream live ledger updates and account changes
#   • Estimate transaction fees from current network conditions
#   • Look up assets, liquidity pools, and order book data
#
# Official Horizon endpoints:
#   Testnet:  https://horizon-testnet.stellar.org
#   Mainnet:  https://horizon.stellar.org
#
# Check Horizon uptime and status:
#   https://stellar.statuspage.io
#
HORIZON_URL=
# StellarKit API environment variables
# Copy this file to `.env` and adjust values as needed.

# Soroban RPC server URL — required for the /soroban/* endpoints
# Testnet default: https://soroban-testnet.stellar.org
# Mainnet has no free SDF-hosted RPC — set your own provider URL
SOROBAN_RPC_URL=

# Server config
# API connectivity
STELLAR_NETWORK=testnet

# Server
PORT=3000

# Logging
# Controls log level: fatal, error, warn, info, debug, trace
# Default: info
LOG_LEVEL=info

# Cache
# Global fallback TTL for in-memory caches (milliseconds).
# Used as the default when a per-endpoint variable is not set.
CACHE_TTL_MS=5000

# Per-endpoint cache TTL overrides (all in milliseconds).
# When set, these take precedence over CACHE_TTL_MS for their respective endpoint.
# Default: 10000 (10 seconds)
CACHE_TTL_NETWORK_STATUS_MS=10000
CACHE_TTL_FEE_ESTIMATE_MS=5000
CACHE_TTL_BASE_FEE_MS=5000
CACHE_TTL_VALIDATORS_MS=300000
CACHE_TTL_ASSET_MS=30000
CACHE_TTL_ASSET_PRICE_MS=5000
CACHE_TTL_TRUSTLINES_MS=15000

# Cache TTL for GET /dex/arbitrage/:code/:issuer (milliseconds)
# Arbitrage opportunity data changes rapidly with market conditions. A short
# window avoids stale paths while still absorbing repeated polling.
# Default: 5000 (5 seconds)
CACHE_TTL_ARBITRAGE_MS=5000

# ============================================================================
# REQUEST BODY SIZE LIMIT
# ============================================================================
# MAX_BODY_SIZE_KB — Maximum allowed JSON request body size in kilobytes.
# Requests that exceed this limit are rejected before reaching any route
# handler and receive a 413 response with the following shape:
#   { success: false, error: { type: "PayloadTooLarge",
#     message: "Request body exceeds the maximum allowed size of <N>KB." } }
#
# Set a low value (e.g. 10) to protect against large-payload memory exhaustion
# attacks. Increase only if specific endpoints genuinely require larger bodies
# (e.g. XDR submission endpoints).
#
# Default: 10 (10 KB)
MAX_BODY_SIZE_KB=10

# API Key authentication
# If set to "true", the API key middleware will require a valid API key
# for protected routes.
REQUIRE_API_KEY=false

# Comma-separated list of valid API keys.
# Example: "validkey1,validkey2".
# Whitespace around keys is trimmed by the middleware.
API_KEYS=validkey1,validkey2


# Slow request detection
# Requests that take longer than this threshold will emit a [SLOW REQUEST] warning
# log entry containing the route, method, duration, and request ID.
# Set to 0 to disable slow request logging.
# Default: 2000 (2 seconds)
SLOW_REQUEST_THRESHOLD_MS=2000

# Cache TTL for GET /account/:id/transaction-count (milliseconds)
# Transaction counts change only when new transactions are submitted, so a
# short window is sufficient to absorb repeated polling without stale risk.
# Default: 20000 (20 seconds)
CACHE_TTL_TX_COUNT_MS=20000

# Cache TTL for GET /soroban/contract/:id/storage (milliseconds)
# Instance storage entries change only when the contract is invoked and writes
# to its persistent storage. A 15-second window absorbs repeated polling while
# staying reasonably fresh for debugging workflows.
# Default: 15000 (15 seconds)
CACHE_TTL_CONTRACT_STORAGE_MS=15000

# Cache TTL for GET /account/:id/asset-balance/:code/:issuer (milliseconds)
# Single trustline balance lookups are called frequently before transactions.
# A short 10-second window reduces Horizon load for repeated polling while
# staying fresh enough for pre-transaction balance checks.
# Default: 10000 (10 seconds)
CACHE_TTL_ASSET_BALANCE_MS=10000

# Cache TTL for GET /account/:id/freeze-status/:assetCode/:assetIssuer (milliseconds)
# Freeze status changes only when the issuer modifies authorization flags, so a
# 30-second window is a safe balance between freshness and Horizon load.
# Default: 30000 (30 seconds)
CACHE_TTL_FREEZE_CHECK_MS=30000

# Cache TTL for GET /account/:id/signing-keys (milliseconds)
# Signing keys change only when the account modifies its signers via set_options.
# Default: 20000 (20 seconds)
CACHE_TTL_SIGNING_KEYS_MS=20000

# Contract Event Poller interval (milliseconds)
# How often the Soroban RPC is polled for new events from registered contracts.
# Applies to the contractEventPoller service used by contract.event webhooks.
# Lower values increase responsiveness but add RPC load.
# Default: 5000 (5 seconds)
CONTRACT_POLL_INTERVAL_MS=5000