LumiBot Environment Variables for Backtests and Scheduled Trading

# environment variables


.. _environment_variables:

Environment Variables
=====================

.. meta::
   :description: LumiBot supports configuring many behaviors via environment variables. This page documents the variables most commonly used for backtesting, ThetaData.

LumiBot supports configuring many behaviors via environment variables. This page documents the variables most commonly used for **backtesting**, **ThetaData**, and **remote caching**.

.. important::

   **Never commit secrets** (API keys, passwords, AWS secret keys) into any repo or docs. Document variable names and semantics only.

Backtesting configuration
-------------------------

LUMIBOT_DISABLE_DOTENV
^^^^^^^^^^^^^^^^^^^^^^




- Notes:
  - When dotenv loading is enabled, LumiBot looks upward from the running script directory for the nearest ``.env`` file. If none is found there, it also checks upward from the current working directory.
  - LumiBot no longer recursively scans every nested directory under the start path. This reduces startup latency and lowers the chance of loading an unrelated nested repo's ``.env`` file.
  - In production/BotManager/BotSpot runs, prefer injected environment variables and set ``LUMIBOT_DISABLE_DOTENV=1`` so local files cannot override runtime secrets.

LUMIBOT_DISABLE_DOTENV_LOCAL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^




- Notes:
  - When dotenv loading is enabled and a ``.env`` file is found, LumiBot also loads a sibling ``.env.local`` after ``.env`` with override behavior.
  - Use ``.env.local`` only for local developer overrides. Do not commit it.
  - Set ``LUMIBOT_DISABLE_DOTENV_LOCAL=1`` in repeatable test or deployment contexts where the base ``.env`` should be loaded but local overrides must be ignored.

LUMIBOT_LOG_LEVEL
^^^^^^^^^^^^^^^^^






IS_BACKTESTING
^^^^^^^^^^^^^^



- It does not choose a runner by itself: a file that only calls
  ``Strategy.backtest()`` still backtests when this is ``False``. A local
  ``IS_BACKTESTING`` assignment in an example is independent of this variable.
  See :doc:`strategy_run_modes`.

BACKTESTING_START / BACKTESTING_END
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




BACKTESTING_BUDGET
^^^^^^^^^^^^^^^^^^



- Notes:
  - When set, this value is preferred over any ``budget=`` passed in strategy code, so it can be controlled per-run via injected environment variables.
  - Default (when unset and no code budget is provided): ``100000``.

LUMIBOT_STRATEGY_PARAMETERS
^^^^^^^^^^^^^^^^^^^^^^^^^^^



- Notes:
  - When set, the parsed dict is merged on top of the strategy's existing ``parameters`` dict with highest priority (wins over both class-level defaults and code-level overrides).
  - Useful for parameter sweeps and for deploying the exact parameter set validated by a backtest.
  - Nested dicts are supported (e.g. ``{"ALLOCATION": {"SPY": 0.50, "IWM": 0.50}}``).
  - Invalid JSON or non-dict values are ignored with a warning.
  - ``BACKTESTING_PARAMETERS`` remains a deprecated compatibility alias for older external runners. If both are present, ``LUMIBOT_STRATEGY_PARAMETERS`` wins.

BOTSPOT_DATA_ROUTING_POLICY
^^^^^^^^^^^^^^^^^^^^^^^^^^^





.. _backtest-data-source-selection:

BACKTESTING_DATA_SOURCE
^^^^^^^^^^^^^^^^^^^^^^^

Choose your backtest data
""""""""""""""""""""""""""""""

This setting selects historical market data for a backtest; it does not choose
your paper/live broker. **A provider setting overrides the class in code**,
including the ``datasource_class`` argument to ``backtest()`` or ``run_backtest()``.

For daily stock and ETF backtests, select Yahoo in your project's ``.env``:

.. code-block:: ini

   BACKTESTING_DATA_SOURCE=yahoo

Or set it in the shell before launching your strategy:

.. code-block:: bash

   # macOS / Linux
   export BACKTESTING_DATA_SOURCE=yahoo
   python my_strategy.py

.. code-block:: powershell

   # Windows PowerShell
   $env:BACKTESTING_DATA_SOURCE = "yahoo"
   python my_strategy.py

Other providers may require credentials or a Data Downloader. See
:doc:`the provider setup guides <backtesting>` for asset coverage and requirements.

.. list-table:: How the data source is selected
   :header-rows: 1
   :widths: 45 55

   * - Configuration
     - Result
   * - Provider name or routing JSON is set
     - Uses that selection, even when Python supplies a class.
   * - Unset; Python supplies a class
     - Uses the class from code.
   * - Unset; Python supplies no class
     - Defaults to ThetaData, which requires its own setup.
   * - ``none`` or an empty value
     - Uses the class from code; raises an error if no class is supplied.

To keep an explicit data-source class in your code, use
``BACKTESTING_DATA_SOURCE=none``. This does not disable data requests or make a
backtest offline.

**Unexpected provider?** Check the variable in your shell, ``.env``, and
``.env.local`` before launching. An exported value takes precedence over the
primary ``.env`` file; ``.env.local`` can override both. See
``LUMIBOT_DISABLE_DOTENV`` and ``LUMIBOT_DISABLE_DOTENV_LOCAL`` above for loading
controls.

Supported values
""""""""""""""""

- Values (case-insensitive):

  - ``thetadata``, ``yahoo``, ``polygon``, ``alpaca``, ``ccxt``, ``databento``, ``polymarket``, ``polymarket_clob``
  - ``ibkr`` / ``interactivebrokersrest`` / ``interactive_brokers_rest`` (IBKR Client Portal REST)
  - ``router`` (multi-provider routing; defaults to Theta for stock/option/index and IBKR for futures/crypto)
  - JSON mapping (multi-provider routing by asset type), e.g. ``{"default":"thetadata","stock":"thetadata","option":"thetadata","index":"thetadata","future":"ibkr","crypto":"ibkr"}``

    - Provider values are case/whitespace/_/- insensitive.
    - Supported values include ``thetadata``, ``ibkr``, ``polygon``, ``alpaca``, ``ccxt``, and ``polymarket``.
    - For CCXT backtesting, you may use ``ccxt`` (auto-select exchange from existing env/credentials) **or** specify a supported CCXT backtesting exchange id directly. Documented backtesting examples are ``kraken``, ``binance``, ``kucoin``, ``bitmex``, ``bybit``, and ``okx``.
    - Routing keys are the canonical asset types (``future``, ``cont_future``, ``crypto``, etc.). Common plural aliases like ``futures``/``cont_futures`` are accepted.

  - ``none`` to disable the env override and rely on code.

Testing / CI guardrails
-----------------------

LUMIBOT_ACCEPTANCE_TRIPWIRE
^^^^^^^^^^^^^^^^^^^^^^^^^^^



- Notes:
  - This is an engineering/CI guardrail to enforce “warm-cache” acceptance backtests. It should not be used for normal production backtests.
  - When triggered, it prints a marker and exits the subprocess with a non-zero code so the test fails reliably.

Live scheduled execution (BotSpot/BotManager)
---------------------------------------------

- ``LUMIBOT_SCHEDULED_EXECUTION``: internal BotManager flag. Truthy values (``1``, ``true``, ``yes``, ``y``, ``on``) make ``Strategy.run_live()`` run one live iteration and exit.
- ``LUMIBOT_LAZY_CREDENTIALS``: defers default broker/data-source credential materialization during live startup when truthy. Defaults to enabled when ``LUMIBOT_SCHEDULED_EXECUTION`` is truthy.
- ``LUMIBOT_CONNECT_STREAM``: overrides whether live brokers start their stream during broker construction. Truthy values enable stream startup; any other set value disables it. Defaults to disabled for scheduled execution and enabled otherwise.
- ``LUMIBOT_START_ORDERS_THREAD``: overrides whether live brokers start their orders thread during broker construction. Truthy values enable the orders thread; any other set value disables it. Defaults to disabled for scheduled execution and enabled otherwise. Queue-based brokers that require the worker to submit orders, such as legacy Interactive Brokers, keep the worker enabled even when this flag is false.
- ``LUMIBOT_SCHEDULED_TARGET_RUN_AT``: UTC ISO-8601 target time for exact scheduled runs. When present, LumiBot initializes the strategy/broker first, waits locally until this timestamp immediately before ``on_trading_iteration()``, and skips the iteration if the drift budget is exceeded.
- ``LUMIBOT_SCHEDULED_PRE_START_AT``: UTC ISO-8601 pre-start time used by BotManager telemetry to compare scheduler launch timing with the requested target.
- ``LUMIBOT_SCHEDULED_TARGET_EVENT``: internal lifecycle selector for a scheduled task. ``closed_market_prepare`` runs ``on_closed_market_iteration()`` only while the market is closed and blocks supported broker order submission, cancellation, and modification APIs for that lifecycle.
- ``LUMIBOT_SCHEDULED_MAX_TARGET_DRIFT_MS``: maximum allowed late drift in milliseconds for exact scheduled runs. Defaults to ``1000``.
- ``LUMIBOT_SCHEDULED_POST_ITERATION_SECONDS``: drain window after the one live iteration. During this window LumiBot continues processing broker/order queue events before exiting.
- ``LUMIBOT_SCHEDULED_TIMING_FILE``: local JSON timing file written by LumiBot for BotManager bootstrap telemetry.
- ``LUMIBOT_SCHEDULED_STATE_BACKEND``: external state backend prepared by BotManager: ``s3``, ``dynamodb``, or ``none``. ``none`` disables scheduled ``self.vars`` file load/save.
- ``LUMIBOT_SCHEDULED_STATE_FILE``: local JSON file managed by BotManager/bootstrap code to restore and persist ``self.vars`` for one scheduled live run. State is restored before scheduled lifecycle hooks.

BotSpot managed research
------------------------

- ``BOTSPOT_RESEARCH_MCP_URL``: optional BotSpot Research MCP endpoint.
- ``BOTSPOT_RESEARCH_MCP_TOKEN``: secret, short-lived bearer capability bound to an authenticated user or hosted deployment.
- ``BOTSPOT_RESEARCH_MCP_RENEW_URL``: optional HTTPS renewal endpoint. Localhost is permitted for local development; otherwise its origin must match the MCP endpoint.
- All three variables are required for automatic attachment. BotSpot-hosted runtimes inject them; external users can link a BotSpot account and configure the same contract.
- Missing or incomplete configuration preserves ordinary LumiBot strategy and agent behavior and emits one deduplicated capability notice.

``GITHUB_TOKEN`` is used only in tagged release CI with repository ``actions: read`` permission to restore compatible agent-eval freshness evidence. The source workflow commit must be an ancestor of the exact tagged candidate. If no trustworthy artifact is available, stale cases run normally. Never log or commit token values.

Backtest artifacts + UX flags
-----------------------------

SHOW_PLOT / SHOW_INDICATORS / SHOW_TEARSHEET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




LUMIBOT_BACKTEST_PARQUET_MODE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


- Values:
  - ``best_effort`` (default): parquet failures log warnings; CSV remains the compatibility layer.
  - ``required``: parquet export failures raise and should fail the backtest (artifact contract mode).
- Notes:
  - This is primarily intended for BotManager/BotSpot backtests where downstream tools depend on Parquet for performance.
  - When set to ``required``, a parquet export error should fail the backtest so missing artifacts are never silently ignored.

BACKTESTING_QUIET_LOGS
^^^^^^^^^^^^^^^^^^^^^^




BACKTESTING_SHOW_PROGRESS_BAR
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




Backtest progress file (BotSpot/BotManager UI)
----------------------------------------------

LOG_BACKTEST_PROGRESS_TO_FILE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



- Notes:
  - On startup, LumiBot writes an initial ``progress.csv`` row immediately to reduce “time-to-first-progress” latency for short backtests.
  - In BotManager, a background thread watches ``/app/logs/*progress.csv`` and uploads the most recent row to DynamoDB.

BACKTESTING_PROGRESS_HEARTBEAT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





BACKTESTING_PROGRESS_HEARTBEAT_SECONDS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





Trade audit telemetry (accuracy investigations)
-----------------------------------------------

LUMIBOT_BACKTEST_AUDIT
^^^^^^^^^^^^^^^^^^^^^^



- Output:
  - Writes a full trade-event export ``*_trade_events.csv`` with ``audit.*`` columns (for example, quote bid/ask snapshots, bar OHLC, SMART_LIMIT inputs, and multileg linkage).
- Notes:
  - This increases CSV width and can add overhead; keep it enabled only when you need a full audit trail.

Profiling (performance + parity investigations)
------------------------------------------------

BACKTESTING_PROFILE
^^^^^^^^^^^^^^^^^^^


- Values:
  - ``yappi`` (supported)
- Output:
  - Produces a ``*_profile_yappi.csv`` artifact alongside other backtest artifacts.

LUMIBOT_CACHE_MISS_DEBUG
^^^^^^^^^^^^^^^^^^^^^^^^






ThetaData option-chain building (performance)
---------------------------------------------

THETADATA_CHAIN_DEFAULT_MAX_DAYS_OUT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^






THETADATA_CHAIN_DEFAULT_MAX_DAYS_OUT_INDEX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^






THETADATA_CHAIN_RECENT_FILE_TOLERANCE_DAYS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





THETADATA_CHAIN_STRIKES_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





THETADATA_CHAIN_STRIKES_BATCH_SIZE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





ThetaData corporate action normalization (accuracy)
------------------------------------------------------------

THETADATA_APPLY_CORPORATE_ACTIONS_INTRADAY
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



- Default:
  - enabled when ``IS_BACKTESTING`` is truthy
  - disabled otherwise
- Notes:
  - Disabling can break options strike selection around splits (example: NVDA 10-for-1 split on 2024-06-10).

Remote cache (S3)
-----------------

LUMIBOT_CACHE_BACKEND / LUMIBOT_CACHE_MODE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


- Common values:
  - ``LUMIBOT_CACHE_BACKEND=s3``
  - ``LUMIBOT_CACHE_MODE=readwrite`` (or ``readonly``)

LUMIBOT_CACHE_FOLDER
^^^^^^^^^^^^^^^^^^^^



LUMIBOT_CACHE_S3_BUCKET / LUMIBOT_CACHE_S3_PREFIX / LUMIBOT_CACHE_S3_REGION
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



LUMIBOT_CACHE_S3_VERSION
^^^^^^^^^^^^^^^^^^^^^^^^




LUMIBOT_CACHE_S3_ACCESS_KEY_ID / LUMIBOT_CACHE_S3_SECRET_ACCESS_KEY / LUMIBOT_CACHE_S3_SESSION_TOKEN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




For cache key layout and validation workflow, see :doc:`Backtesting <backtesting>` and the engineering notes in ``docs/remote_cache.md``.

Strategy configuration
----------------------

STRATEGY_NAME
^^^^^^^^^^^^^




MARKET
^^^^^^




HIDE_TRADES / HIDE_POSITIONS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^





DISCORD_WEBHOOK_URL
^^^^^^^^^^^^^^^^^^^




Database configuration
----------------------

DB_CONNECTION_STR
^^^^^^^^^^^^^^^^^





LOG_BACKTEST_PROGRESS_TO_FILE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




Broker selection
----------------

TRADING_BROKER
^^^^^^^^^^^^^^


- Values (case-insensitive):
  - ``alpaca``, ``tradier``, ``ccxt``, ``coinbase``, ``kraken``, ``weex``
  - ``ib``, ``interactivebrokers``, ``ibrest``, ``interactivebrokersrest``
  - ``tradovate``, ``schwab``, ``bitunix``, ``polymarket``, ``polymarket_clob``
  - ``projectx`` / ``projectx-topstepx`` for TopstepX futures (via ProjectX)


DATA_SOURCE
^^^^^^^^^^^


- Values (case-insensitive):
  - ``alpaca``, ``tradier``, ``polygon``, ``yahoo``, ``thetadata``, ``databento``
  - ``ccxt``, ``coinbase``, ``kraken``, ``weex``, ``schwab``, ``bitunix``, ``projectx``, ``polymarket``, ``polymarket_clob``


Alpaca broker
-------------

ALPACA_API_KEY / ALPACA_API_SECRET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




ALPACA_OAUTH_TOKEN
^^^^^^^^^^^^^^^^^^





ALPACA_IS_PAPER
^^^^^^^^^^^^^^^





ALPACA_NEWS_API_KEY / ALPACA_NEWS_API_SECRET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





Polymarket CLOB broker
----------------------

POLYMARKET_PRIVATE_KEY
^^^^^^^^^^^^^^^^^^^^^^





POLYMARKET_WALLET_ADDRESS
^^^^^^^^^^^^^^^^^^^^^^^^^




POLYMARKET_OWNER_ADDRESS
^^^^^^^^^^^^^^^^^^^^^^^^


  and value reads when it differs from ``POLYMARKET_WALLET_ADDRESS``.


POLYMARKET_SIGNATURE_TYPE
^^^^^^^^^^^^^^^^^^^^^^^^^



  wallet / ``POLY_1271``.

  explicitly for live testing and Bot Manager deployments.

POLYMARKET_CLOB_API_KEY / POLYMARKET_CLOB_API_SECRET / POLYMARKET_CLOB_API_PASSPHRASE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





POLYMARKET_API_CREDENTIALS_JSON
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





POLYMARKET_RELAYER_API_KEY / POLYMARKET_RELAYER_API_KEY_ADDRESS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




  secret, and passphrase fields for private order/balance/trade endpoints and WebSocket user streams.

POLYMARKET_BUILDER_CODE
^^^^^^^^^^^^^^^^^^^^^^^




POLYMARKET_AUTO_APPROVE
^^^^^^^^^^^^^^^^^^^^^^^





POLYMARKET_MAX_MARKET_ORDER_NOTIONAL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





POLYMARKET_TEST_TOKEN_ID / POLYMARKET_LIVE_TRADING_ENABLED / POLYMARKET_TEST_MAX_NOTIONAL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





  values, redact output, and only submit live orders when the live gate and caps are present. The LumiBot smoke helper
  supports explicit order-matrix cases such as ``fak-buy``, ``fok-buy``, ``fak-sell``, ``fok-sell``, ``gtc-buy``,
  ``gtd-buy``, ``post-only-buy``, ``cancel-single``, ``cancel-multiple``, ``cancel-all``, ``cancel-market``, and
  ``--websocket``.

Polymarket CLOB implementation notes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Set ``TRADING_BROKER=polymarket`` for the normal live broker path. ``DATA_SOURCE=polymarket`` is only the optional
  separate public-market-data override.
- CLOB collateral balances are returned in 6-decimal raw units by balance/allowance reads. LumiBot scales those values
  into dollars before returning account cash.
- The current international CLOB adapter supports read-only account state, market discovery, token resolution, order
  books, quotes, last price, supported price history, public market WebSockets, and authenticated user WebSocket
  subscription. Live submit/cancel is implemented and has been proven through the LumiBot broker with a funded deposit
  wallet, pUSD approvals, and conditional-token sell approvals. Existing Magic/proxy accounts may still be rejected by
  Polymarket with a deposit-wallet/API-key binding error until migrated through the supported deposit-wallet flow.
- SELL orders need conditional-token approvals from the deposit wallet. The local setup helper can submit these approvals
  with ``scripts/polymarket_deposit_wallet_setup.py --approve-conditional``.

Tradier broker
--------------

TRADIER_ACCESS_TOKEN
^^^^^^^^^^^^^^^^^^^^




TRADIER_TOKEN_PATH
^^^^^^^^^^^^^^^^^^



  ``refresh_token``, ``expires_in``, and ``issued_at``.

  token payload back to this file atomically. If the file cannot be written,
  refresh fails instead of silently continuing with only in-memory token state.

LUMIBOT_OAUTH_REFRESH_MODE
^^^^^^^^^^^^^^^^^^^^^^^^^^


  Tradier token-file integrations.

  the configured token file. ``external`` means LumiBot does not call the provider OAuth refresh endpoint; a trusted
  parent process must atomically replace the configured token file, and LumiBot reloads it before broker requests and
  after auth failures.

  handling. The token file still needs a valid access token for broker API calls.

TRADIER_ACCOUNT_NUMBER
^^^^^^^^^^^^^^^^^^^^^^




TRADIER_IS_PAPER
^^^^^^^^^^^^^^^^





Interactive Brokers
-------------------

INTERACTIVE_BROKERS_PORT
^^^^^^^^^^^^^^^^^^^^^^^^




INTERACTIVE_BROKERS_CLIENT_ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




INTERACTIVE_BROKERS_IP
^^^^^^^^^^^^^^^^^^^^^^





IB_SUBACCOUNT
^^^^^^^^^^^^^




Interactive Brokers REST
------------------------

IB_USERNAME / IB_PASSWORD
^^^^^^^^^^^^^^^^^^^^^^^^^




IB_ACCOUNT_ID
^^^^^^^^^^^^^




IB_API_URL
^^^^^^^^^^




IB_GATEWAY_PORT
^^^^^^^^^^^^^^^





IB_GATEWAY_INSTANCE_ID
^^^^^^^^^^^^^^^^^^^^^^





IB_USE_PAPER_ACCOUNT
^^^^^^^^^^^^^^^^^^^^





IBEAM_DOCKER_TAG
^^^^^^^^^^^^^^^^





IB_AUTH_TIMEOUT / IB_AUTH_POLL_INTERVAL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





IB_REQUEST_TIMEOUT
^^^^^^^^^^^^^^^^^^





IB_VERIFY_SSL
^^^^^^^^^^^^^





IBKR_HISTORY_SOURCE
^^^^^^^^^^^^^^^^^^^





IBKR_FUTURES_EXCHANGE
^^^^^^^^^^^^^^^^^^^^^





IBKR_CRYPTO_VENUE
^^^^^^^^^^^^^^^^^





LUMIBOT_IBKR_ENABLE_FUTURES_BID_ASK
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





Schwab broker
-------------

SCHWAB_ACCOUNT_NUMBER
^^^^^^^^^^^^^^^^^^^^^




SCHWAB_APP_KEY / SCHWAB_APP_SECRET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




SCHWAB_TOKEN
^^^^^^^^^^^^




SCHWAB_BACKEND_CALLBACK_URL
^^^^^^^^^^^^^^^^^^^^^^^^^^^




SCHWAB_CANCEL_DIAGNOSTICS
^^^^^^^^^^^^^^^^^^^^^^^^^





Tradovate broker
----------------

TRADOVATE_USERNAME / TRADOVATE_DEDICATED_PASSWORD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




TRADOVATE_APP_ID / TRADOVATE_APP_VERSION
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





TRADOVATE_CID / TRADOVATE_SECRET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




TRADOVATE_IS_PAPER
^^^^^^^^^^^^^^^^^^





TRADOVATE_MD_URL
^^^^^^^^^^^^^^^^





Crypto brokers (CCXT)
---------------------

KRAKEN_API_KEY / KRAKEN_API_SECRET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




COINBASE_API_KEY_NAME / COINBASE_PRIVATE_KEY
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




COINBASE_API_PASSPHRASE
^^^^^^^^^^^^^^^^^^^^^^^




COINBASE_SANDBOX
^^^^^^^^^^^^^^^^





Bitunix broker
--------------

BITUNIX_API_KEY / BITUNIX_API_SECRET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




BITUNIX_TRADING_MODE
^^^^^^^^^^^^^^^^^^^^





ProjectX brokers
----------------

ProjectX support is primarily documented for TopstepX futures. The lower-level adapter can read firm-specific ProjectX environment variable prefixes, but new firms should be tested before being treated as production-ready.

PROJECTX_FIRM
^^^^^^^^^^^^^




PROJECTX_{FIRM}_API_KEY
^^^^^^^^^^^^^^^^^^^^^^^





PROJECTX_{FIRM}_USERNAME
^^^^^^^^^^^^^^^^^^^^^^^^





PROJECTX_{FIRM}_PREFERRED_ACCOUNT_NAME
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





Data source credentials
-----------------------

POLYGON_API_KEY
^^^^^^^^^^^^^^^




POLYGON_MAX_MEMORY_BYTES
^^^^^^^^^^^^^^^^^^^^^^^^




LUMIBOT_OPTION_CHAIN_MAX_DAYS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


  simulated date through that many days ahead, which keeps a free Polygon key under its rate
  limit. A limited chain is cached under its own name (``<SYMBOL>_<date>_max<N>d.parquet``) and is
  only reused on the same day with the same limit, never as a full chain.

  are ignored with a warning.


THETADATA_USERNAME / THETADATA_PASSWORD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





THETADATA_BASE_URL
^^^^^^^^^^^^^^^^^^






DATABENTO_API_KEY
^^^^^^^^^^^^^^^^^




DATABENTO_TIMEOUT
^^^^^^^^^^^^^^^^^





DATABENTO_MAX_RETRIES
^^^^^^^^^^^^^^^^^^^^^





LUMIWEALTH_API_KEY
^^^^^^^^^^^^^^^^^^




LISTENER_WRITE_URL
^^^^^^^^^^^^^^^^^^





  observations separate from the default listener.

Runtime telemetry (memory/health)
---------------------------------

LUMIBOT_TELEMETRY
^^^^^^^^^^^^^^^^^





LUMIBOT_TELEMETRY_INTERVAL_SECONDS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^





LUMIBOT_TELEMETRY_DEEP
^^^^^^^^^^^^^^^^^^^^^^





Notes:

- Burst mode (more frequent telemetry logs) turns on automatically above ~80% of container memory.
- Deep snapshots trigger above ~90% with a ~1 hour cooldown (these thresholds are fixed defaults today).

AI agent model providers
------------------------

LumiBot's AI agent subsystem (``self.agents.create(model=...)`` or ``default_model=...``) supports multiple LLM providers. You only need the key matching the provider id you pass for each agent. Non-Gemini ids are routed through LiteLLM, which ships as a LumiBot dependency. In BotSpot managed runtimes, an owner-bound managed AI capability may be supplied when no provider key is present. A user-provided key always takes precedence and provider errors never fall back to managed credits.

LUMIBOT_AI_GATEWAY_URL and LUMIBOT_AI_GATEWAY_TOKEN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


- These values are issued and renewed by BotSpot. Users should not create or save them manually.
- The token is short-lived and deployment-bound. LumiBot renews it through the gateway so always-on bots can continue without receiving a long-lived provider credential.
- Supported managed providers are Gemini, OpenAI, Anthropic, and xAI. Other providers continue to require their normal provider key.
- Any configured provider key below takes precedence for that provider.

GEMINI_API_KEY
^^^^^^^^^^^^^^



- Required when ``default_model`` starts with ``gemini-`` (e.g. ``gemini-3.1-flash-lite-preview``).
- LumiBot's public contract is ``GEMINI_API_KEY``. Do not rely on Google SDK
  alias names in strategy examples or downstream products that infer required
  runtime secrets.

OPENAI_API_KEY
^^^^^^^^^^^^^^



- Required for the default model and whenever ``default_model`` is any other ``openai/...`` id.

XAI_API_KEY or GROK_API_KEY
^^^^^^^^^^^^^^^^^^^^^^^^^^^



- Required when ``default_model`` looks like ``xai/grok-4.20-0309-reasoning`` or any other ``xai/...`` id.
- ``XAI_API_KEY`` is the canonical provider env var; ``GROK_API_KEY`` is also accepted for user-facing Grok naming.

ANTHROPIC_API_KEY
^^^^^^^^^^^^^^^^^



- Required when ``default_model`` looks like ``anthropic/claude-opus-4-7`` or any other ``anthropic/...`` id.

Other providers (Groq, Mistral, Cohere, Fireworks, Together, etc.) use the provider-prefixed id format and the corresponding provider env var; see the LiteLLM documentation for the full list.

SEC fundamentals and agent memory
---------------------------------

LUMIBOT_SEC_USER_AGENT
^^^^^^^^^^^^^^^^^^^^^^





LUMIBOT_SEC_CACHE_DIR
^^^^^^^^^^^^^^^^^^^^^




FRED_API_KEY
^^^^^^^^^^^^




  ``realtime_start`` and ``realtime_end`` for point-in-time backtests.
  Built-in FRED agent tools are not exposed during backtests without this key
  because LumiBot does not use revised public CSV fallbacks for macro data.

LUMIBOT_FRED_CACHE_DIR
^^^^^^^^^^^^^^^^^^^^^^




LUMIBOT_MEMORY_DIR
^^^^^^^^^^^^^^^^^^




LUMIBOT_MEMORY_EXPORT_PARQUET
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


  events, retrievals, and current state.


  artifacts for DuckDB queries, BotSpot uploads, and post-run inspection.

LUMIBOT_AGENT_MEMORY_NOTE_MAX_CHARS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


  agent prompt.


  compacts the lightweight runtime notes so repeated backtest iterations do not
  blow up the model context window.

LUMIBOT_AGENT_MAX_MODEL_CALLS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




  cap is reached. Use this for expensive AI backtests and smoke runs where
  accidental spend matters.

LUMIBOT_AGENT_MAX_RUN_ATTEMPTS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




  not multiply model spend across many simulated iterations.

Telegram notifications
----------------------

TELEGRAM_BOT_TOKEN
^^^^^^^^^^^^^^^^^^




TELEGRAM_CHAT_ID
^^^^^^^^^^^^^^^^