Paper Trading

Paper trading allows you to test your trading strategies in real-time using live market data without risking actual capital. The Hydra provides a high-fidelity simulation environment that matches your orders against live orderbooks while accounting for fees, latency, and fill probabilities.

Overview

In paper trading mode, the bot connects to:

• Polymarket: To receive live orderbook updates and market events.
• Binance: To receive reference price data for cross-exchange arbitrage or price discovery.

Instead of sending real orders to the Polymarket exchange, the bot uses a SimExecution engine. This engine evaluates your trading intents against the current state of the market to determine if and when a trade would have been filled.

Getting Started

To start the bot in paper trading mode, use the following command:

# Using the hydra binary
hydra run

# Or from source
bun run paper

Using Preset Configs

For quick setup, you can use one of the preset configuration files:

# Using the hydra binary
hydra run --config configs/paper-testing.yaml

# Or from source
BOT_CONFIG=configs/paper-testing.yaml bun run paper

By default, if BOT_CONFIG is not set, the bot will look for config.yaml or config.example.yaml.

By default, this will load the configuration from config.example.yaml. You can specify a custom configuration file using the --config flag or BOT_CONFIG environment variable:

# Using the hydra binary
hydra run --config ./my-config.yaml

# Or from source
BOT_CONFIG=./my-config.yaml bun run paper

Simulation Configuration

The behavior of the paper trading engine is controlled by the simulation block in your configuration file.

simulation:
  # Initial USDC balance for the session
  initialBalanceUSDC: 10000

  # Simulated trading fees
  feeModel:
    maker: 0.0001 # 0.01% maker fee
    taker: 0.0002 # 0.02% taker fee

  # Simulated network latency in milliseconds
  latencyMs: 150

  # Probability (0.0 to 1.0) that a limit order is filled
  fillProbability: 0.95

  # Liquidity-aware partial fill simulation
  partialFillEnabled: true
  liquidityDepthUSDC: 1000
  slippagePerSize: 0.001

Parameters

• initialBalanceUSDC: The starting balance for your paper trading session. The simulation engine tracks this balance, updating it in real-time as orders are filled and fees are deducted.
• feeModel: Defines the fees applied to every simulated trade. These fees are deducted from the simulated balance to provide an accurate representation of net profitability.
• latencyMs: Adds a delay between the bot’s decision and the simulated execution. This is critical for testing latency-sensitive strategies like arbitrage.
• fillProbability: In real markets, being at the front of the queue is not guaranteed. This parameter simulates the risk of not getting filled even when the price reaches your limit.
• partialFillEnabled: When enabled, orders will only fill up to the simulated liquidity available at the target price level.
• liquidityDepthUSDC: The amount of liquidity (in USDC) assumed to be available at each price increment in the order book.
• slippagePerSize: Models price impact. Your fill price will be adjusted based on the size of your order relative to the simulated liquidity.

Monitoring Trades

You can monitor your paper trading session in real-time using the Terminal User Interface (TUI).

While the paper trading script is running, open a new terminal window and run:

# Using the hydra binary
hydra tui

# Or from source
bun run tui

The TUI connects to the bot via IPC (Inter-Process Communication) and displays:

• Active markets and their current prices.
• Simulated positions and balances.
• Recent event logs and trade executions.
• Performance metrics (PnL, volume).

Trade History

In addition to the full event logs, all simulated trades are recorded in the Trade Ledger. This provides a concise, append-only history of your paper trading performance.

You can view the trade history at any time using the CLI:

hydra trades --mode paper

See the Trade Ledger guide for more details on analyzing your results.

Event Logs

Every event during a paper trading session—including market updates, strategy signals, and simulated fills—is logged to a JSONL file for later analysis.

Logs are stored in the directory specified by persistence.outDir in your config:

persistence:
  outDir: "./runs"

Each session creates a unique subdirectory with a timestamp (e.g., runs/paper_1736512345678/events.jsonl). These logs are compatible with the bot’s backtesting tools, allowing you to replay and analyze your strategy’s performance in detail.