Snapshots & Equity
Snapshots capture your account state at regular intervals and after key events, building a time-series of your portfolio's performance.
What's Captured
Each snapshot records:
| Field | Description |
|---|---|
timestamp | When the snapshot was taken |
trigger | What triggered it: scheduled, post-push, post-reject |
netLiquidation | Total account value (cash + positions) |
totalCashValue | Cash balance |
unrealizedPnL | Unrealized profit/loss across all positions |
realizedPnL | Realized profit/loss |
positions | Array of current positions with quantities, costs, and market values |
Triggers
Snapshots are taken automatically in three cases:
- Scheduled — Periodic snapshots at a configurable interval (default: every 15 minutes). Managed by the snapshot scheduler via the cron engine.
- Post-push — Immediately after a trading commit is pushed (order executed). Captures the account state right after a trade.
- Post-reject — After a commit is rejected by the user. Records the state at the time of rejection.
Configuration
Configure in data/config/snapshot.json:
{
"enabled": true,
"every": "15m"
}
| Field | Description |
|---|---|
enabled | Enable/disable scheduled snapshots |
every | Interval for scheduled snapshots (e.g. "15m", "1h", "30m") |
Post-push and post-reject snapshots are always taken regardless of this setting.
Storage
Snapshots are stored as JSONL files per account:
data/trading/{accountId}/snapshots/
Each file contains one snapshot per line, making it easy to process with standard tools.
Equity Curve
The Web UI builds an equity curve from snapshot history, showing your portfolio value over time. This visualization helps you:
- Track overall performance trends
- Spot drawdowns and recovery periods
- Compare performance across accounts
- See the impact of specific trades
Resilience
Skipped snapshots — If the broker is unreachable when a scheduled snapshot fires, it's skipped rather than storing stale data. A snapshot.skipped event is logged.
Retry — When taking snapshots across all accounts, failed accounts get one automatic retry after a 3-second delay.
Carry-forward — The equity curve visualization handles gaps gracefully, carrying forward the last known value when snapshots are missing.
Aggregated Equity
The AccountManager can aggregate equity across all enabled accounts, giving you a unified view of your total portfolio value even when running multiple broker accounts.