Configuration reference
Both processes read plain environment variables (a .env file at the repository
root is loaded when present; real environment variables win). Invalid configuration
exits with code 78 (EX_CONFIG) before a port is bound or a tool is served — a
process that starts on half-valid configuration would advertise capability it
cannot honour.
Each table below is generated from a CONFIG_REFERENCE table that lives beside
the package's loadConfig; a unit test in each package fails if the table and
the loader drift apart.
Facilitator (packages/facilitator)
| Variable | Required | Default | Format | Description |
|---|---|---|---|---|
NETWORK |
no | stellar:testnet |
one of: stellar:testnet, stellar:pubnet | CAIP-2 identifier of the Stellar network this facilitator serves (FACTS F-004). One facilitator process serves exactly one network. |
RPC_URL |
on stellar:pubnet | https://soroban-testnet.stellar.org (testnet only) |
http(s) URL | Soroban RPC endpoint used for simulation, submission, and ledger reads. Pubnet has no public default RPC, so the variable is required there (FACTS F-004). |
SUBMITTER_SECRET (alias: FACILITATOR_STELLAR_PRIVATE_KEY) |
yes | — | one 'S...' Ed25519 secret seed, or a comma-separated list | The account(s) that source settlement transactions and sponsor their network fees. Multiple seeds enable the package's round-robin signer selection (DECISIONS D-012). The alias exists so an environment prepared for the x402 e2e suite works unchanged (FACTS F-056). |
FEE_BUMP_SECRET |
no | — | 'S...' Ed25519 secret seed | Dedicated fee account. When set, each settlement is wrapped in a fee-bump transaction, decoupling fee payment from sequence-number management — the posture the reference operator runs in production (FACTS F-047, F-055; DECISIONS D-012). |
PORT |
no | 4021 |
integer in [1, 65535] | TCP port the HTTP server listens on. |
FEE_MODE |
no | free |
one of: free | Service-fee posture. 'free' — no walras fee on top of the sponsored network fee — is the only implemented mode; any other value is a startup error rather than a silent fallback. Distinct from extra.areFeesSponsored, which is about network fees and is always true (FACTS F-006). |
DB_PATH |
no | ./data/catalog.db |
filesystem path, or ':memory:' | SQLite file backing the discovery catalog (WAL journal mode; DECISIONS D-023). The store creates the file on first open. |
MAX_TRANSACTION_FEE_STROOPS |
no | 50000 |
positive integer (stroops) | Settlement-fee safety ceiling passed to the payment scheme (FACTS F-037). Measured settlements run at ~23 000 stroops (FACTS F-069), so the default leaves roughly 2x headroom. |
MCP server (packages/mcp-server)
| Variable | Required | Default | Format | Description |
|---|---|---|---|---|
FACILITATOR_URL |
no | http://127.0.0.1:4021 |
http(s) URL | Base URL of the walras facilitator whose discovery endpoints search_resources queries and whose settlements paid_call pays through. |
WALRAS_MCP_NETWORK |
no | stellar:testnet |
CAIP-2 network identifier | The one network this server's wallet pays on. A 402 demanding any other network is declined by policy before anything is signed (DECISIONS D-030). |
WALRAS_MCP_MAX_AMOUNT |
no | 10000000 (1 USDC) |
non-negative integer, asset base units (USDC: 7 decimals, FACTS F-008) | Per-call spend cap, enforced twice: as a pre-payment check against the probed 402, and as a payment-requirements policy on the shared x402 client so no transport can bypass it (FACTS F-081; DECISIONS D-030). |
CLIENT_STELLAR_PRIVATE_KEY |
no | — | 'S...' Ed25519 secret seed (56 chars) | The paying wallet. Unset, the server runs search-only and paid_call names the gap (walras_mcp_wallet_not_configured). A malformed value — including the .env.example placeholder — is a startup error (exit 78), never a late payment failure. |
References
FACTS rows and DECISIONS entries cited in the descriptions above resolve in
../FACTS.md and ../DECISIONS.md.