Paper Trading

[kutay25]

Summary

• Implements paper trading client to lighter-python
• Taker-only simulated trading against live or snapshot Lighter order books, no real transactions
• Perps only, cross-margin only, no funding simulation

What's included

• lighter/paper_client/ package: types, matching engine, accounting, risk/liquidation, order book runtime
• Snapshot mode: fetch order book via REST, simulate trades against it
• Live mode: private websocket connection per market, continuous book updates, automatic liquidation checks
• Matching is read-only and never mutates the tracked book
• Position accounting mirrors backend semantics (open/reduce/flip/close, proportional entry quote)
• Risk engine: TAV, IMR, MMR, closeout margin, leverage, margin usage, liquidation price
• Market scoped liquidation

Testing and Examples

• 3 example scripts under examples/
• 61 unit tests to cover various behaviours.

---

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 18 additional findings in Devin Review.

[devin-ai-integration]

Devin Review found 1 new potential issue.

🐛 1 issue in files not directly in the diff

🐛 Duplicate field names in Candle model destroy 5 of 12 data fields (lighter/models/candle.py:34-39)

The revert commit renamed the uppercase Pydantic field names (O, H, L, C, V) to lowercase (o, h, l, c, v), creating duplicates with the existing lowercase fields on lines 30–33 and 38. In Pydantic v2, the second definition silently overrides the first, so the model collapses from 12 fields to 7. The plain o (open), h (high), l (low), c (close), and v (volume0) fields are completely lost — their definitions are replaced by the aliased raw variants.

Verified impact via runtime test

Confirmed via Candle.model_fields: only 7 fields remain (t, o (alias=O), h (alias=H), l (alias=L), c (alias=C), v (alias=V), i). When validating {"o": 100, "O": 99, ...}, accessing candle.o returns 99 (the raw value) not 100 (the open value). model_dump(by_alias=True) produces only 7 keys, omitting o, h, l, c, v entirely.

View 18 additional findings in Devin Review.