Trading Mode - Autonome

Autonome supports two trading modes: simulated (safe testing with virtual capital) and live (real trades on zkLighter exchange). The mode is controlled by the TRADING_MODE environment variable.

Trading Modes

Simulated Mode

Runs a local trading simulator that mimics exchange behavior without risking real capital. Perfect for:

Testing trading strategies
Validating AI model decisions
Development and debugging
Backtesting with live market data

Features:

Virtual capital (configurable starting balance)
Real market price data
Simulated order execution and fills
Position tracking and P&L calculation
No real money at risk

Live Mode

Executes real trades on the zkLighter exchange using your API credentials. Use this mode when:

You’ve thoroughly tested your strategy in simulation
You’re ready to trade with real capital
You understand the risks and have proper risk management

Live mode executes real trades with real money. Always test thoroughly in simulated mode first and never risk more capital than you can afford to lose.

Configuration

Set the trading mode in your .env file:

# .env or .env.local

# For safe testing (default)
TRADING_MODE=simulated

# For real trading
TRADING_MODE=live

Simulated Mode Configuration

When using TRADING_MODE=simulated, configure the simulator with these variables:

# Starting capital in quote currency
SIM_INITIAL_CAPITAL=10000

# Quote currency for positions (usually USDT)
SIM_QUOTE_CURRENCY=USDT

# How often to refresh market data (milliseconds)
SIM_REFRESH_INTERVAL_MS=10000

number

default:"10000"

Starting capital for the simulator. This represents your virtual trading balance in the quote currency.

string

default:"USDT"

The quote currency for all positions and P&L calculations. Typically USDT or USDC.

number

default:"10000"

Interval in milliseconds between market data refreshes. Lower values provide more real-time updates but increase API usage.

Live Mode Configuration

When using TRADING_MODE=live, you must configure Lighter API credentials:

# Lighter exchange credentials
LIGHTER_API_KEY_INDEX=2
LIGHTER_BASE_URL=https://mainnet.zklighter.elliot.ai

number

default:"2"

Your API key index in the zkLighter account system. Each account can have multiple key indexes.

string (URL)

default:"https://mainnet.zklighter.elliot.ai"

Base URL for the Lighter REST API. Use mainnet for production trading.

Your LIGHTER_API_KEY_INDEX provides access to your exchange account and funds. Never share this value or commit it to version control.

Accessing Trading Mode in Code

Use the validated constants from src/env.ts:

import { TRADING_MODE, IS_SIMULATION_ENABLED, DEFAULT_SIMULATOR_OPTIONS } from "@/env";

// Check current mode
if (IS_SIMULATION_ENABLED) {
  console.log("Running in simulated mode");
  console.log("Initial capital:", DEFAULT_SIMULATOR_OPTIONS.initialCapital);
} else {
  console.log("Running in LIVE mode - real trades!");
}

// Access mode directly
const mode = TRADING_MODE; // "simulated" | "live"

Type-Safe Mode Checking

The TRADING_MODE constant is type-checked as an enum:

import type { TradingMode } from "@/server/features/simulator/types";
import { TRADING_MODE } from "@/env";

// TypeScript knows this is "simulated" | "live"
const currentMode: TradingMode = TRADING_MODE;

// Type-safe conditional logic
if (TRADING_MODE === "live") {
  // Execute real trade
} else {
  // Execute simulated trade
}

Simulator Architecture

The exchange simulator (ExchangeSimulator) provides a high-fidelity trading environment:

Key Features

State Management:

Maintains virtual account balance and positions
Tracks open orders and execution history
Calculates unrealized P&L from live market prices
Persists state to database (rehydrates on restart)

Order Processing:

Validates order parameters (quantity, price, side)
Simulates order matching and fills
Applies realistic slippage and fees
Supports market and limit orders

Market Data:

Fetches real-time prices from configured data sources
Updates position values on price changes
Triggers position refreshes at configured intervals

Database Integration:

Stores all simulated trades in the Orders table with status="CLOSED"
Tracks open positions as orders with status="OPEN"
Maintains full audit trail of simulated trading activity

Simulator Initialization

The simulator is bootstrapped once at server startup:

// src/server/schedulers/bootstrap.ts
import { IS_SIMULATION_ENABLED } from "@/env";
import { getExchangeSimulator } from "@/server/features/simulator/instance";

export async function bootstrapSchedulers() {
  if (IS_SIMULATION_ENABLED) {
    const simulator = getExchangeSimulator();
    await simulator.initialize();
    console.log("✓ Exchange simulator initialized");
  }
}

The bootstrap is called from the API server entry point (api/src/index.ts) and guarded against duplicate initialization using schedulerState.ts.

Switching Modes

To switch between modes:

Update your .env file:

# Change this line
TRADING_MODE=simulated  # or "live"

Restart the application:

# Development
bun run dev:all

# Production
bun run build:api
bun run start:api

Verify the mode in logs:

✓ Trading mode: simulated
✓ Exchange simulator initialized

Always verify the mode after restart. There is no hot-reloading for TRADING_MODE - you must restart the server for changes to take effect.

Safety Features

Mode Isolation

Simulated and live modes are completely isolated:

Simulated trades never reach the real exchange
Live trades never interact with simulator state
Database records are tagged with execution context
Position calculations respect mode boundaries

Pre-Deployment Checklist

Before enabling live mode:

Thoroughly tested strategy in simulated mode
Verified P&L calculations are accurate
Confirmed risk management rules are working
Set appropriate position sizing limits
Configured stop losses and invalidation levels
Tested with small capital amounts first
Verified Lighter API credentials are correct
Set up monitoring and alerts
Documented your trading rules and expectations

Environment Validation

Validate your configuration before deployment:

bun run scripts/validate-env.ts

This script checks:

Required variables are set for your chosen mode
API keys are present (for live mode)
URLs are valid and reachable
Database connection is working
Simulator configuration is valid (for simulated mode)

Common Patterns

Conditional Feature Flags

Enable features based on trading mode:

import { IS_SIMULATION_ENABLED } from "@/env";

// Only show simulator controls in simulated mode
const showSimulatorControls = IS_SIMULATION_ENABLED;

// Adjust UI messaging based on mode
const orderButtonText = IS_SIMULATION_ENABLED 
  ? "Place Simulated Order" 
  : "Place Live Order";

Mode-Specific Logging

Add context to logs:

import { TRADING_MODE } from "@/env";
import * as Sentry from "@sentry/react";

Sentry.startSpan(
  { 
    name: "placeOrder",
    attributes: { tradingMode: TRADING_MODE }
  },
  async () => {
    console.log(`[${TRADING_MODE.toUpperCase()}] Placing order...`);
    // Order logic
  }
);

Testing Both Modes

Use different .env files for different scenarios:

# .env.test (for CI/automated tests)
TRADING_MODE=simulated
SIM_INITIAL_CAPITAL=10000

# .env.staging (for staging environment)
TRADING_MODE=simulated
SIM_INITIAL_CAPITAL=100000

# .env.production (for live trading)
TRADING_MODE=live
LIGHTER_API_KEY_INDEX=2

Troubleshooting

Simulator Not Initializing

Symptoms: No positions showing, orders not executing in simulated mode Solutions:

Check TRADING_MODE=simulated is set
Verify database connection (DATABASE_URL)
Check server logs for initialization errors
Ensure scheduler bootstrap completed successfully

Live Orders Not Executing

Symptoms: Orders placed but not filled in live mode Solutions:

Verify TRADING_MODE=live is set
Check Lighter API credentials are correct
Confirm LIGHTER_BASE_URL is reachable
Review exchange API logs for errors
Check account balance and permissions

Mode Mismatch After Restart

Symptoms: UI shows different mode than expected Solutions:

Verify .env file was saved
Restart both API server and frontend
Clear browser cache and reload
Check for multiple .env files that might conflict

Best Practices

Development:

Always use simulated mode during development
Test edge cases with various capital amounts
Validate strategy performance over extended periods
Use realistic refresh intervals (don’t set too low)

Testing:

Run integration tests in simulated mode
Verify mode switching doesn’t break features
Test with both empty and populated order history
Validate P&L calculations match expectations

Production:

Never commit live API credentials
Use environment-specific .env files
Monitor mode in server logs and metrics
Implement circuit breakers for live trading
Start with minimal capital to verify behavior

Security:

Store live API keys in secure secret management
Rotate credentials regularly
Use separate accounts for testing and production
Audit all live trade executions
Set up alerts for unexpected trading activity

​Trading Modes

​Simulated Mode

​Live Mode

​Configuration

​Simulated Mode Configuration

​Live Mode Configuration

​Accessing Trading Mode in Code

​Type-Safe Mode Checking

​Simulator Architecture

​Key Features

​Simulator Initialization

​Switching Modes

​Safety Features

​Mode Isolation

​Pre-Deployment Checklist

​Environment Validation

​Common Patterns

​Conditional Feature Flags

​Mode-Specific Logging

​Testing Both Modes

​Troubleshooting

​Simulator Not Initializing

​Live Orders Not Executing

​Mode Mismatch After Restart

​Best Practices

Trading Modes

Simulated Mode

Live Mode

Configuration

Simulated Mode Configuration

Live Mode Configuration

Accessing Trading Mode in Code

Type-Safe Mode Checking

Simulator Architecture

Key Features

Simulator Initialization

Switching Modes

Safety Features

Mode Isolation

Pre-Deployment Checklist

Environment Validation

Common Patterns

Conditional Feature Flags

Mode-Specific Logging

Testing Both Modes

Troubleshooting

Simulator Not Initializing

Live Orders Not Executing

Mode Mismatch After Restart

Best Practices