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.
• common.v1.Decimal is one field: the number in base 10. There is no numeric twin beside it, so there is no precedence to get wrong and no silent zero when a producer picks the other form. to_decimal writes it and validates the grammar the message documents; from_decimal reads it back into a decimal.Decimal, which is exact — a 96-bit coefficient over 28 decimal places survives it intact. A value too wide or too deep for a decimal is rejected, never truncated, and a payload nobody populated is an error rather than a zero.

License

Apache-2.0 — see the repository LICENSE.