LongTrader
English | 中文
Local strategy host for portable trading strategies over a contract-first ConnectRPC API. Strategies depend only on generated protobuf ports; the daemon/terminal backend is pluggable, and the same strategy ships in Rust, Python, TypeScript and Go.
Status: open-source preview. The contract under
proto/is the single source of truth (bufmanaged); all language SDKs are thin wrappers over generated stubs. Built from the ground up as an original LongTrader implementation.
Features
- Contract-first —
proto/longtrader/**defines trading, market, worker, data and backtest services. Breaking changes are checked bybuf breakingin CI. - Portable strategies — 20+ native strategies under
bin/longtrader-worker/src/strategies/depend only onTradingGateway/MarketDataSourcetraits (ports.rs). No hidden domain coupling. - Session control plane — deterministic
ATTACHED → SYNCING → ACTIVE → KILL_SWITCH_TRIPPEDlifecycle, atomicReconcileStatesnapshot, 3× heartbeat lease, per-sessionKillSwitchPolicy(session/all/none). - Thin SDKs —
sdks/{python,typescript,go}mirror the same 6-dir canonical layout (contract/session/ports/adapters/strategies/examples). Generated code is never hand-edited. - Worker hardening —
tracingonly,eyre/thiserrorerror split,hpx+rustls,tokioasync, strictclippy::pedantic/nurserylints.
Architecture
proto/ # buf v2, single source of truth (longtrader.*.v1)
crates/longtrader-contract/ # generated types + ConnectRPC traits (build.rs → buffa/connectrpc)
bin/longtrader-worker/ # strategy host: ports, session, adapters, envelope, strategies
bin/longtrader-cli/ # CLI client for Terminal API (binary: longtrader)
sdks/{python,typescript,go}/ # thin wrappers over generated stubs (contract/session/ports/...)
Canonical layout per language:
| Canonical dir | Rust | Python | TypeScript | Go |
|---|---|---|---|---|
contract/ |
crates/longtrader-contract |
sdks/python/longtrader_sdk/proto/ |
sdks/typescript/src/gen/ |
sdks/go/gen/ |
session/ |
bin/longtrader-worker/src/session/ |
longtrader_sdk/session.py |
src/session.ts |
session/ |
ports/ |
src/ports.rs |
longtrader_sdk/ports.py |
src/ports.ts |
ports/ |
adapters/ |
src/adapters/{remote,mock}.rs |
Connect-over-httpx in session.py |
Connect-over-undici in session.ts |
Connect-over-http in session/ |
strategies/ |
src/strategies/ |
examples/grid_strategy.py |
examples/grid_strategy.ts |
strategies/ |
examples/ |
examples/ / docs/ |
sdks/python/examples/ |
sdks/typescript/examples/ |
sdks/go/examples/ |
CLI (longtrader-cli)
The longtrader-cli binary provides a command-line interface to the LongTrader Terminal API. Binary name: longtrader.
# Build
# Global flags
# Commands
Timeframes: M1, M5, M15, M30, H1, H4, D1, W1.
Topics: MARKET_LITE, MARKET_HEAVY, TRADING, RUNTIME, FUNDING, DERIVATIVES.
Quick Start
Prerequisites: Rust stable + nightly (rustfmt/clippy), just, buf (for contract lint/generation).
# Contract
# Run worker (example)
# Build and run CLI
Minimal config.toml:
= "http://127.0.0.1:8080"
= "http://127.0.0.1:7888" # when set, backend = "terminal"
= "/run/secrets/longtrader_token"
= "127.0.0.1:9000" # WorkerSessionService + proxies
[]
= "simple_grid"
[]
= "BTCUSDT"
= "mock"
= "90000"
= "110000"
= 10
= "0.001"
Token is loaded from api_token_file only (trimmed, never logged); Authorization: Bearer <token> is sent over hpx with rustls.
SDKs
# Python
# TypeScript
&& &&
# Go (generated stubs via buf, paths=source_relative)
Minimal use (same lifecycle in every language — Attach → heartbeat → ReconcileState gate to ACTIVE):
=
=
import { Session } from "@longtrader/sdk";
const s = await Session.attach("http://127.0.0.1:8080", "YOUR_TERMINAL_TOKEN");
s.startHeartbeat();
const snap = await s.reconcileState();
console.log(s.sessionId, s.state, snap.snapshotSequence);
s.stop();
Strategies
Each strategy under bin/longtrader-worker/src/strategies/<name>/ ships a README.md and is selected via strategy.type:
| Category | Strategies |
|---|---|
| Grid / Market Making | simple_grid, boll_grid, hedge_grid, fixed_maker, cross_maker, cross_depth_maker, cross_fixed_maker |
| Trend Following | ema_cross, supertrend |
| Portfolio & Rebalancing | rebalance, market_cap, dca_scheduler |
| Risk & Operations | sentinel, autoborrow, balance_align, convert, deposit_transfer |
| Signals & Analytics | irr, nav_recorder, premium_monitor, random_entry, xfunding_lite |
All strategies are original LongTrader implementations and use only ports::{TradingGateway, MarketDataSource}; transport selection lives in adapters/.
Development
Workspace rules: root [workspace.dependencies] carries numeric versions only (no default features); sub-crates use workspace = true. Prefer hpx over reqwest, tokio for async, tracing for observability.
Security
- No secrets are committed. Tokens are file-loaded (
api_token_file) and compared with constant-timesubtle. proto/longtrader/exchange/v1/exchange_daemon.protowas removed in this open-source release (legacy private daemon API). Uselongtrader.market/trading/stream/ops.v1instead.- Report vulnerabilities via GitHub Security Advisories; do not open public issues for sensitive reports.
License
Apache-2.0 — see LICENSE. SDK packages (sdks/python, sdks/typescript) are also Apache-2.0 unless noted otherwise.
Acknowledgements
Built with buffa/connectrpc, hpx, tokio, rust_decimal, buf.