Configuration Reference

The bot is configured via a YAML file. By default, it looks for ./config.example.yaml, but you can override this with the BOT_CONFIG environment variable.

Preset Configs

Several preset configuration files are available in the configs/ directory for different risk profiles:

configs/conservative.yaml: Low risk, quarter-Kelly sizing, tight limits.
configs/aggressive.yaml: Higher risk, half-Kelly sizing, more aggressive thresholds.
configs/paper-testing.yaml: Relaxed settings optimized for development and testing.

Full Schema

mode: paper | replay | live

ipc:
  host: "127.0.0.1"      # IPC server bind address
  port: 9876             # IPC server port (1-65535)

persistence:
  outDir: "./out"        # Output directory for sessions
  snapshotIntervalMs: 1000  # State snapshot interval (min: 100)

risk:
  staleness:
    polymarketWsMs: 5000    # Max age for Polymarket data
    binanceWsMs: 2000       # Max age for Binance data
    chainlinkMs: 60000      # Max age for Chainlink data
  reconciliation:
    enabled: true           # Enable position reconciliation
    intervalMs: 60000       # Reconciliation interval (min: 1000)
  limits:
    maxDrawdownPercent: 10  # Max drawdown before kill (0-100)
    maxPositionSizeUSDC: 1000  # Max single position size
    maxTotalExposureUSDC: 5000  # Max total exposure across all positions
    maxDailyLossUSDC: 500   # Max loss in a single UTC day
    maxDailyLossPercent: 5  # Max % loss in a single UTC day
    maxActiveMarkets: 3     # Max concurrent markets
    maxOrdersPerMinute: 60  # Rate limit for orders
    priceBanding:
      minPrice: 0.02        # Min allowed price
      maxPrice: 0.98        # Max allowed price
      maxDeviationFromMid: 0.10  # Max deviation from mid
    slippageProtection:
      minLiquidityUSDC: 50  # Min liquidity at target price
      maxSlippagePercent: 0.05  # Max slippage (5%)

simulation:
  initialBalanceUSDC: 10000  # Initial balance for paper trading
  feeModel:
    maker: 0.0             # Maker fee (0 = 0%)
    taker: 0.001           # Taker fee (0.001 = 0.1%)
  latencyMs: 50            # Simulated execution latency
  fillProbability: 0.95    # Probability of fill (0-1)
  partialFillEnabled: true # Enable liquidity-aware fills
  liquidityDepthUSDC: 1000 # Simulated liquidity per price level
  slippagePerSize: 0.001   # Slippage per unit (0.001 = 0.1%)

markets:
  coins:                   # Coins to trade
    - Bitcoin
    - Ethereum
  durations:               # Market durations to consider
    - 5m
    - 15m
  maxMarkets: 5            # Max markets to trade simultaneously
  scoring:                 # Market scoring parameters
    minVolume24hr: 100     # Min 24h volume filter
    minLiquidity: 100      # Min liquidity filter
    maxSpread: 0.15        # Max bid-ask spread filter
    maxStrikeDistancePercent: 0.15  # Max strike distance from spot
    strikeProximityWeight: 0.35     # Weight for strike proximity
    volumeWeight: 0.25              # Weight for volume
    liquidityWeight: 0.20           # Weight for liquidity
    spreadWeight: 0.10              # Weight for spread
    edgeWeight: 0.10                # Weight for edge potential

strategies:
  enabled:                 # Strategies to run
    - latency_arb

  latency_arb:
    edgeThreshold: 0.02    # Min edge to trade (0-1)
    maxPositionSize: 10    # Max contracts per position
    cooldownMs: 5000       # Cooldown between trades
    volatilityWindowMs: 300000  # Window for volatility calc
    minVolatility: 0.1     # Min volatility to trade
    takerFeeBps: 100       # Taker fee in basis points
    assetMapping:          # Map slug patterns to assets
      bitcoin: BTC
      ethereum: ETH
      solana: SOL
    kelly:                 # Kelly criterion position sizing
      enabled: false
      fraction: 0.25       # Quarter Kelly (less aggressive)
      minSize: 1
      maxSize: 100
      bankroll: 10000

  dip_arb:
    slidingWindowMs: 60000    # Window for dip detection
    dipThreshold: 0.05        # Min dip size
    sumTarget: 1.0            # Target sum of YES+NO prices
    leg2TimeoutSeconds: 30    # Timeout for second leg
    minProfitRate: 0.01       # Min profit rate
    splitOrders: false        # Split orders across books
    autoMerge: false          # Auto-merge positions

  threshold_farm:
    sumTarget: 1.0            # Target YES+NO sum
    minProfitRate: 0.005      # Min profit rate (-1 to 1)

replay:
  input: "./out/record_xxx/events.jsonl"  # Replay input file

alerting:
  webhookUrl: "https://hooks.slack.com/..."  # Webhook URL
  events:                   # Events to alert on
    - kill_switch
    - risk_trip
    - error
  throttleMs: 60000         # Throttle per event type (ms)

priceFeed:
  mode: single              # single | consolidated
  throttleMs: 0             # Throttle for consolidated mode (0 = disabled)
  aggregationMethod: median # median | mean | first
  exchanges:
    binance:
      enabled: true
    coinbase:
      enabled: false

telemetry:
  enabled: false
  host: "127.0.0.1"
  port: 8094
  protocol: udp
  database: "hydra"
  batchSize: 100
  flushIntervalMs: 1000
  globalTags:
    env: production

ntp:
  enabled: false
  syncIntervalMs: 60000
  maxOffsetWarningMs: 100
  maxOffsetKillMs: 500

Section Details

`mode`

Value	Description
`paper`	Simulated trading with live data
`replay`	Replay recorded sessions
`live`	Real trading (coming soon)

`ipc`

IPC server for TUI and remote control.

Field	Type	Default	Description
`host`	string	`127.0.0.1`	Bind address
`port`	number	-	Port number (1-65535)

`persistence`

Session persistence settings.

Field	Type	Default	Description
`outDir`	string	-	Output directory path
`snapshotIntervalMs`	number	`1000`	Snapshot interval in ms (min: 100)

`risk`

Risk management configuration.

`risk.staleness`

Maximum data age before considering it stale.

Field	Type	Description
`polymarketWsMs`	number	Max Polymarket data age
`binanceWsMs`	number	Max Binance data age
`chainlinkMs`	number	Max Chainlink data age

`risk.reconciliation`

Position reconciliation with exchange.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable reconciliation
`intervalMs`	number	`60000`	Check interval (min: 1000)
`positionTolerancePercent`	number	`0.01`	Allowed position mismatch tolerance (1% default). Mismatches within this threshold are logged as warnings rather than triggering the kill switch.

`risk.limits`

Trading limits and circuit breakers.

Field	Type	Description
`maxDrawdownPercent`	number	Max drawdown before kill (0-100)
`maxPositionSizeUSDC`	number	Max single position size
`maxTotalExposureUSDC`	number	Max total exposure across all positions
`maxDailyLossUSDC`	number	Max loss in a single UTC day (USDC)
`maxDailyLossPercent`	number	Max loss in a single UTC day (%)
`maxOrdersPerMinute`	number	Order rate limit
`maxActiveMarkets`	number	Max concurrent markets with active positions

`risk.limits.priceBanding`

Price sanity checks to reject extreme orders.

Field	Type	Description
`minPrice`	number	Minimum allowed price (e.g., 0.02)
`maxPrice`	number	Maximum allowed price (e.g., 0.98)
`maxDeviationFromMid`	number	Max deviation from mid price (e.g., 0.10 = 10%)

`risk.limits.slippageProtection`

Liquidity checks before execution.

Field	Type	Description
`minLiquidityUSDC`	number	Min available liquidity at target price
`maxSlippagePercent`	number	Max acceptable slippage (0.05 = 5%)

`alerting`

Remote webhook alerts for critical events.

Field	Type	Default	Description
`webhookUrl`	string	-	Webhook URL (Slack, Discord, etc.)
`events`	string[]	`["kill_switch", "risk_trip", "error"]`	Events to alert on
`throttleMs`	number	`60000`	Throttle alerts per event type (ms)

Available events:

kill_switch - Kill switch triggered
risk_trip - Risk breaker tripped
order_placed - Order placed
order_filled - Order filled
error - Error occurred
session_start - Bot started
session_stop - Bot stopped

`priceFeed`

Reference price sourcing configuration.

Field	Type	Default	Description
`mode`	string	`single`	Price feed mode: `single` (Binance only) or `consolidated` (multi-exchange)
`throttleMs`	number	`0`	Throttle consolidated price updates (ms). Default is 0 for minimum latency.
`aggregationMethod`	string	`median`	Aggregation: `median`, `mean`, or `first`

Binance Safety Features

The Binance feed includes built-in safety mechanisms that are active by default:

Sequence Gap Detection: Monitors Binance updateId for missing messages.
- Warning: Triggered at a gap of 100 messages.
- Kill Switch: Triggered at a gap of 500 messages to prevent trading on corrupt order book state.
Heartbeat: Maintains connection health during quiet market periods.
Backpressure Handling: Monitors message queue depth during high volatility.
- Warning: Triggered when queue exceeds 100 messages.
- Kill Switch: Triggered when queue exceeds 1000 messages to prevent memory exhaustion and stale data.

Binance Advanced Options

For advanced users, additional Binance WebSocket options are available:

Field	Type	Default	Description
`fastParse`	boolean	`false`	Use regex-based parser instead of JSON.parse (~58% faster, less robust)
`backpressure.enabled`	boolean	`true`	Enable queue depth monitoring
`backpressure.warnThreshold`	number	`100`	Queue depth that triggers warning
`backpressure.killThreshold`	number	`1000`	Queue depth that triggers kill switch

Note: fastParse is opt-in because while faster, it only handles the expected bookTicker format and may silently skip malformed messages. Only enable if latency is critical.

`priceFeed.exchanges`

Exchange-specific settings for consolidated mode.

Field	Type	Default	Description
`binance.enabled`	boolean	`true`	Enable Binance price feed
`coinbase.enabled`	boolean	`false`	Enable Coinbase price feed

`telemetry`

Streaming metrics to InfluxDB via Telegraf using line protocol.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable telemetry
`host`	string	`127.0.0.1`	Telegraf/InfluxDB host
`port`	number	`8094`	Telegraf/InfluxDB port (8094 for UDP, 8086 for HTTP)
`protocol`	string	`udp`	`udp` or `http`
`database`	string	`hydra`	InfluxDB database name
`prefix`	string	`hydra`	Measurement prefix
`batchSize`	number	`100`	Batch size before flushing
`flushIntervalMs`	number	`100`	Flush interval in ms (min: 10)
`globalTags`	record	-	Global tags for all metrics

HFT-Grade Telemetry

Hydra is designed for high-frequency trading where every microsecond counts. To maintain this performance, the telemetry system uses several specialized features:

Push-based Architecture: Unlike Prometheus which “pulls” metrics (causing CPU spikes and jitter), Hydra “pushes” metrics to Telegraf/InfluxDB. This ensures that metric collection never interrupts critical trading logic.
High-Resolution Timestamps: Uses performance.now() for sub-millisecond precision instead of the standard 1ms Date.now().
Tick-to-Trade Latency: Tracks the time from the exchange’s timestamp (exchangeTsMs) to the bot’s arrival time (arrivalTsMs) and finally to the order send time (sendTsMs).
Event Loop Monitoring: Detects when the JavaScript event loop is blocked for more than 10ms, which could delay order execution.

`ntp`

Clock synchronization via HTTP Date headers to ensure millisecond-level accuracy.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable NTP sync
`servers`	string[]	See below	List of HTTP time servers
`syncIntervalMs`	number	`60000`	Interval between syncs
`timeoutMs`	number	`3000`	Request timeout
`maxOffsetWarningMs`	number	`100`	Offset to trigger warning
`maxOffsetKillMs`	number	`500`	Offset to trigger kill switch
`samplesPerSync`	number	`3`	Number of servers to sample per sync

Default servers:

https://time.cloudflare.com
https://www.google.com
https://www.microsoft.com

`simulation`

Paper trading simulation parameters.

`simulation.feeModel`

Field	Type	Default	Description
`maker`	number	-	Maker fee rate (0.001 = 0.1%)
`taker`	number	-	Taker fee rate

Other simulation fields

Field	Type	Default	Description
`initialBalanceUSDC`	number	`10000`	Initial USDC balance for simulation
`latencyMs`	number	`0`	Simulated execution latency
`fillProbability`	number	`1`	Fill probability (0-1)
`partialFillEnabled`	boolean	`false`	Enable liquidity-aware partial fills
`liquidityDepthUSDC`	number	`1000`	Simulated liquidity at each price level
`slippagePerSize`	number	`0.001`	Price impact per unit size (0.1% default)

`markets`

Market selection and scoring.

Field	Type	Default	Description
`discoveryMode`	string	`series`	Discovery mode: `series` or `legacy`
`coins`	string[]	`["Bitcoin", "Ethereum"]`	Coins to trade (filters discovered markets)
`durations`	string[]	`["5m", "15m"]`	Market durations
`maxMarkets`	number	`5`	Max concurrent markets

`markets.series`

Configuration for series-based discovery.

Field	Type	Default	Description
`category`	string	`crypto-updown`	Category of markets to discover
`timeWindows`	string[]	`["15m", "hourly", "daily"]`	Time windows to target, in priority order

`markets.scoring`

Market scoring parameters for smart discovery.

Field	Type	Default	Description
`minVolume24hr`	number	`100`	Min 24h volume filter
`minLiquidity`	number	`100`	Min liquidity filter
`maxSpread`	number	`0.15`	Max spread filter
`maxStrikeDistancePercent`	number	`0.15`	Max strike distance
`strikeProximityWeight`	number	`0.35`	Strike proximity weight
`volumeWeight`	number	`0.25`	Volume weight
`liquidityWeight`	number	`0.20`	Liquidity weight
`spreadWeight`	number	`0.10`	Spread weight
`edgeWeight`	number	`0.10`	Edge weight

Note: Weights should sum to 1.0 for normalized scoring.

`strategies`

Strategy configuration.

`strategies.enabled`

Array of strategy names to run. Options:

latency_arb - Latency arbitrage
dip_arb - Dip arbitrage
threshold_farm - Threshold farming
always_buy - Always buy (testing only)

`strategies.latency_arb`

Field	Type	Default	Description
`edgeThreshold`	number	`0.02`	Min edge to trade (0-1)
`maxPositionSize`	number	`10`	Max contracts
`cooldownMs`	number	`5000`	Trade cooldown
`volatilityWindowMs`	number	`300000`	Volatility window
`minVolatility`	number	`0.1`	Min volatility
`takerFeeBps`	number	`100`	Taker fee in basis points
`closeoutBufferMs`	number	`60000`	Time before expiry to stop entering new trades
`modelUncertaintyEnabled`	boolean	`true`	Add dynamic buffer to edge threshold
`assetMapping`	record	See below	Maps slug patterns to assets

`strategies.latency_arb.exit`

Exit logic configuration.

Field	Type	Default	Description
`reverseEdgeThreshold`	number	`0.01`	Exit when edge reverses beyond this (1%)
`minEdgeToHold`	number	`0.005`	Exit when edge decays below this (0.5%)
`flattenOnCloseout`	boolean	`true`	Force flatten positions in closeout buffer
`exitCooldownMs`	number	`2000`	Cooldown between exit attempts

`strategies.latency_arb.assetMapping`

Allows adding support for new assets without code changes.

assetMapping:
  bitcoin: BTC
  btc: BTC
  ethereum: ETH
  eth: ETH
  solana: SOL
  sol: SOL
  dogecoin: DOGE
  doge: DOGE

`strategies.latency_arb.kelly`

Kelly criterion position sizing for optimal bet sizing based on edge.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable Kelly sizing
`fraction`	number	`0.25`	Kelly fraction (0.25 = quarter Kelly)
`minSize`	number	`1`	Minimum position size
`maxSize`	number	`100`	Maximum position size
`bankroll`	number	`10000`	Bankroll for Kelly calculation
`uncertaintyDiscount`	number	`1.0`	Reduce size by this factor (0-1) to account for edge estimation uncertainty
`correlatedPositions`	number	`1`	Number of correlated positions; size reduced by 1/sqrt(N)

Note: Full Kelly (fraction=1.0) is mathematically optimal but very aggressive. Quarter Kelly (0.25) is recommended for real trading to reduce variance.

Uncertainty adjustments:

uncertaintyDiscount: 0.7 means “I’m 70% confident in my edge estimate”, so size = 70% of Kelly size
correlatedPositions: 4 with 4 BTC markets means each gets 50% size (1/sqrt(4)) to account for correlated outcomes

`strategies.dip_arb`

Field	Type	Default	Description
`slidingWindowMs`	number	-	Dip detection window
`dipThreshold`	number	-	Min dip size
`sumTarget`	number	-	Target YES+NO sum
`leg2TimeoutSeconds`	number	-	Second leg timeout
`minProfitRate`	number	-	Min profit rate
`splitOrders`	boolean	`false`	Split orders
`autoMerge`	boolean	`false`	Auto-merge positions

`strategies.threshold_farm`

Field	Type	Default	Description
`sumTarget`	number	-	Target YES+NO sum
`minProfitRate`	number	-	Min profit rate (-1 to 1)

`replay`

Replay mode configuration.

Field	Type	Description
`input`	string	Path to events.jsonl file

Example Configurations

Conservative Paper Trading

mode: paper

ipc:
  host: "127.0.0.1"
  port: 9876

persistence:
  outDir: "./out"
  snapshotIntervalMs: 1000

risk:
  staleness:
    polymarketWsMs: 3000
    binanceWsMs: 1000
    chainlinkMs: 30000
  limits:
    maxDrawdownPercent: 5
    maxPositionSizeUSDC: 100
    maxOrdersPerMinute: 10

simulation:
  initialBalanceUSDC: 5000
  feeModel:
    maker: 0.0
    taker: 0.002
  latencyMs: 100
  fillProbability: 0.9

markets:
  coins:
    - Bitcoin
  maxMarkets: 2
  scoring:
    minVolume24hr: 500
    maxSpread: 0.10

strategies:
  enabled:
    - latency_arb
  latency_arb:
    edgeThreshold: 0.03
    maxPositionSize: 5
    cooldownMs: 10000

Aggressive Multi-Market

mode: paper

ipc:
  host: "127.0.0.1"
  port: 9876

persistence:
  outDir: "./out"

risk:
  staleness:
    polymarketWsMs: 5000
    binanceWsMs: 2000
    chainlinkMs: 60000

simulation:
  initialBalanceUSDC: 50000
  feeModel:
    maker: 0.0
    taker: 0.001
  latencyMs: 25
  fillProbability: 1.0

markets:
  coins:
    - Bitcoin
    - Ethereum
    - Solana
  durations:
    - 5m
    - 15m
    - 1h
  maxMarkets: 10
  scoring:
    minVolume24hr: 50
    maxSpread: 0.20
    maxStrikeDistancePercent: 0.20

strategies:
  enabled:
    - latency_arb
  latency_arb:
    edgeThreshold: 0.015
    maxPositionSize: 20
    cooldownMs: 2000
    minVolatility: 0.05