Trade Ledger

Hydra includes a built-in trade ledger system that automatically logs every fill event to an append-only file. This provides a durable audit trail of all trading activity, separate from the high-volume event logs.

Overview

The Trade Ledger captures essential details for every trade, including execution price, size, fees, and the specific signal or reason that triggered the trade. It is designed for:

• Auditability: Maintain a permanent record of all live and paper trades.
• Performance Analysis: Calculate P&L, volume, and fee statistics.
• Strategy Refinement: Analyze the “edge” and reference prices at the time of execution.

Automatic Logging

The ledger is integrated with the system’s EventBus. Whenever an OrderFill event occurs, the TradeSubscriber automatically enriches the data and appends it to the appropriate ledger file.

Storage Location

Ledger files are stored in JSON Lines (.jsonl) format in the data/ledger/ directory:

Mode	Path
Paper	data/ledger/trades-paper.jsonl
Live	data/ledger/trades-live.jsonl
Replay	data/ledger/trades-replay.jsonl

Viewing Trades

You can view and analyze your trade history using the hydra trades command.

Basic Usage

To view all trades from the paper trading ledger:

hydra trades

To view live trades:

hydra trades --mode live

Filtering Results

You can filter the output by market, side, or limit the number of results:

# Show only the last 10 trades
hydra trades -n 10

# Show trades for a specific market
hydra trades --market 0x...

# Show only sell orders
hydra trades --side SELL

Summary Statistics

To see aggregated performance metrics instead of individual trades, use the --summary flag:

hydra trades --summary

This provides:

• Total trade count (buys vs. sells)
• Total volume in USDC
• Total fees paid
• Net realized P&L
• Breakdown by market (trade count, volume, net position)

Data Format

Each entry in the .jsonl file is a TradeRecord object. If you need to perform custom analysis, you can export the ledger as JSON:

hydra trades --json > my_trades.json

Trade Record Schema

Field	Type	Description
tradeId	string	Unique identifier for the fill.
marketId	string	The ID of the market traded.
side	string	BUY or SELL.
token	string	UP or DOWN.
price	number	The execution price.
size	number	Quantity of tokens filled.
valueUSDC	number	Total value (price * size).
feePaid	number	Fees incurred for the trade.
tsMs	number	Unix timestamp in milliseconds.
mode	string	paper, live, or replay.
reason	string	The signal/reason that triggered the trade.
refPrice	number	The reference price (e.g. Binance) at trade time.
edge	number	The calculated edge/alpha at trade time.

Programmatic Access

You can also interact with the ledger programmatically using the internal ledger module:

import { loadAllTrades, computeTradeSummary } from "./core/ledger";

const trades = await loadAllTrades("./data/ledger/trades-live.jsonl");
const summary = computeTradeSummary(trades);

console.log(`Net P&L: $${summary.netPnL}`);