longtrader-sdk (Python)

Tier-2 thin wrapper over the generated longtrader Connect stubs. Hand-written code stays minimal — session handling plus overflow policies — while all trading semantics live in the contract (proto/, buf-managed).

Installation

pip install longtrader-sdk

The published wheel bundles the generated protobuf stubs, so no code-generation step is required for end users. Generate stubs locally only when building from source (repo just sdk-generate).

Requirements: Python >= 3.10.

Canonical layout (design doc §6.8)

Concept names match the TypeScript/Rust wrappers 1:1 (Session, TradingPort, MarketPort, sync_state(), OverflowPolicy).

Proto namespaces

Generated stubs are produced by just sdk-generate into longtrader_sdk/proto/ (never hand-edit).

Quickstart

just sdk-generate          # generates stubs into longtrader_sdk/proto/
pip install -e sdks/python
python sdks/python/examples/grid_strategy.py --help

Minimal use:

from longtrader_sdk import Session

s = Session.attach("http://127.0.0.1:8080", token="YOUR_TERMINAL_TOKEN")
s.start_heartbeat()
snapshot = s.reconcile_state()   # gate to ACTIVE; pre-ACTIVE orders are rejected
print(s.session_id, s.state, snapshot.snapshot_sequence)
s.close()

Wire notes

• Unary calls: POST {base}/longtrader.worker.v1.WorkerSessionService/{Method}, Content-Type: application/proto; errors arrive as non-200 JSON bodies surfaced as ConnectError (.code, .details).
• Server-streaming uses application/connect+proto with 5-byte envelopes (1 flag byte + u32 big-endian length; flag 0x02 = end-of-stream JSON). See docs/bare-protocol-guide.md sections 4–5.
• Auth is the existing terminal API token passed to AttachSession.
• OverflowPolicy governs event-queue behavior under slow consumers (DROP_OLDEST preserves newest, COALESCE last-writer-wins, BLOCK applies backpressure); sequence gaps require snapshot resync/reconcile.

License

Apache-2.0 — see the repository LICENSE.