longtrader-cli 0.2.1

Connect-RPC CLI client for longtrader-api (longtrader.terminal.v1)
<div align="center">

# LongTrader

**A local strategy host for portable trading strategies over a contract-first ConnectRPC API.**

[![Rust](https://img.shields.io/badge/language-Rust-DEA584?logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Contract: buf v2](https://img.shields.io/badge/contract-buf%20v2-9cf.svg)](proto/)
[![CI](https://img.shields.io/badge/CI-clippy%20%2B%20tests%20%2B%20buf%20breaking-2ea043.svg)](#development)
[![Crates.io: longtrader-cli](https://img.shields.io/crates/v/longtrader-cli.svg)](https://crates.io/crates/longtrader-cli)
[![PyPI: longtrader-sdk](https://img.shields.io/pypi/v/longtrader-sdk.svg)](https://pypi.org/project/longtrader-sdk/)
[![npm: @longcipher/longtrader-sdk](https://img.shields.io/npm/v/@longcipher/longtrader-sdk.svg)](https://www.npmjs.com/package/@longcipher/longtrader-sdk)

*Write a strategy once. Run it in Rust, Python, TypeScript, or Go against the same generated, versioned contract. Your backend is a detail.*

[English](README.md) · [中文](README.zh.md) · [Architecture](docs/architecture.md) · [Getting Started](docs/getting-started.md) · [Bare Protocol Guide](docs/bare-protocol-guide.md)

</div>

---

## Why LongTrader

Most trading frameworks lock you into one language, one exchange SDK, and one deploy target. LongTrader takes the opposite stance:

- **The contract is the product.** Every service, message, and wire format under `proto/` is the single source of truth, managed with [`buf`]https://buf.build. The Rust domain, the Python/TypeScript/Go SDKs, and the Terminal backend are all *thin consumers* of generated stubs. Breaking changes are caught by `buf breaking` in CI before they ever ship.
- **Strategies are portable.** A grid or trend strategy depends only on two traits — `TradingGateway` and `MarketDataSource`. There is no hidden domain coupling, no exchange-specific import, no framework magic. The same strategy ships in four languages.
- **The backend is pluggable.** Run against a mock venue, a private terminal, or your own daemon. Swap transports in the `adapters/` layer without touching a single strategy line.
- **The control plane is deterministic.** Session lifecycle (`ATTACHED → SYNCING → ACTIVE → KILL_SWITCH_TRIPPED`) is a real state machine with a 3× heartbeat lease, an atomic reconcile snapshot, and a per-session kill-switch policy. Losing the lease cancels your orders — by design.

> **Status:** open-source preview. Built from the ground up as an original LongTrader implementation. The contract is stable at `longtrader.*.v1`; SDKs are thin wrappers over generated stubs and are never hand-edited.

---

## What you get

| | |
|---|---|
| **Contract-first API** | `proto/longtrader/**` defines trading, market, worker/session, data, backtest, ops and stream services. `buf breaking` guards every PR. |
| **55 native strategies** | Grid / market-making, trend-following, arbitrage, execution algos, portfolio rebalancing, risk & operations, and analytics — each isolated behind `ports.rs`. |
| **Deterministic session control plane** | Lease-based liveness, atomic `ReconcileState`, per-session `KillSwitchPolicy` (`session` / `all` / `none`). |
| **Thin, consistent SDKs** | Python, TypeScript, and Go mirrors of the same canonical layout. Generated code is never hand-edited. |
| **Hardened worker** | `tracing`-only observability, `eyre`/`thiserror` error split, `hpx` + `rustls` transport, `tokio` async, and strict `clippy::pedantic`/`nursery` lints under `-D warnings`. |
| **Local-first, secret-safe** | Tokens load from a file only (constant-time `subtle` compare, never logged). No secrets are committed. |

---

## Architecture

LongTrader is a hexagonal host. Strategies talk to *ports*; adapters own the transport; the contract owns the wire.

```mermaid
flowchart LR
    subgraph Strategies["Strategies (Rust / Py / TS / Go)"]
        S[strategy logic]
    end
    subgraph Ports["Ports (the seam)"]
        T[TradingGateway]
        M[MarketDataSource]
        F[FundingRateSource]
        O[VenueOpInvoker]
    end
    subgraph Adapters["Adapters"]
        R[RemoteAdapter<br/>ConnectRPC + hpx/rustls]
        K[MockAdapter<br/>offline dry-run]
    end
    subgraph Contract["Contract (proto/, buf-managed)"]
        C[longtrader.trading/market/worker/stream.v1]
    end
    subgraph Backend["Backend (pluggable)"]
        B[Terminal / Daemon / Mock]
    end

    S --> T & M & F & O
    T & M & F & O --> R & K
    R --> C --> B
    K --> B
```

Text form (canonical layers):

```
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 the 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/contract/` (hand-written codec) + optional `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` | `examples/grid_strategy.go` |
| `examples/` | `examples/` / `docs/` | `sdks/python/examples/` | `sdks/typescript/examples/` | `sdks/go/examples/` |

---

## Packages

| Language | Package | Registry |
|---|---|---|
| Rust (contract) | [`longtrader-contract`]https://crates.io/crates/longtrader-contract | [![crates.io]https://img.shields.io/crates/v/longtrader-contract.svg]https://crates.io/crates/longtrader-contract |
| Rust (protocol) | [`longtrader-proto`]https://crates.io/crates/longtrader-proto | [![crates.io]https://img.shields.io/crates/v/longtrader-proto.svg]https://crates.io/crates/longtrader-proto |
| Rust (CLI) | [`longtrader-cli`]https://crates.io/crates/longtrader-cli | [![crates.io]https://img.shields.io/crates/v/longtrader-cli.svg]https://crates.io/crates/longtrader-cli |
| Rust (worker) | [`longtrader-worker`]https://crates.io/crates/longtrader-worker | [![crates.io]https://img.shields.io/crates/v/longtrader-worker.svg]https://crates.io/crates/longtrader-worker |
| Python | [`longtrader-sdk`]https://pypi.org/project/longtrader-sdk/ | [![PyPI]https://img.shields.io/pypi/v/longtrader-sdk.svg]https://pypi.org/project/longtrader-sdk/ |
| TypeScript | [`@longcipher/longtrader-sdk`]https://www.npmjs.com/package/@longcipher/longtrader-sdk | [![npm]https://img.shields.io/npm/v/@longcipher/longtrader-sdk.svg]https://www.npmjs.com/package/@longcipher/longtrader-sdk |
| Go | [`sdks/go`]https://pkg.go.dev/github.com/longcipher/longtrader/sdks/go | [![Go Reference]https://pkg.go.dev/badge/github.com/longcipher/longtrader/sdks/go.svg]https://pkg.go.dev/github.com/longcipher/longtrader/sdks/go |

> The Go SDK implements the same `Session` lifecycle, the full trading and
> market surfaces, and the `TradingPort`/`MarketPort` seam, with a
> dependency-free hand-written protobuf codec — see [sdks/go/README.md]sdks/go/README.md.

---

## Quick start

### Prerequisites

Rust stable + nightly (`rustfmt`/`clippy`), [`just`](https://github.com/casey/just), and [`buf`](https://buf.build) (for contract lint/generation).

```bash
just setup          # installs cargo-mutants, cargo-shear, cargo-sort, typos, rumdl
just check          # cargo check --all-targets --all-features
just lint           # typos + rumdl + cargo sort/fmt + clippy -D warnings + shear
just test           # cargo test --all-features (unit + proptest)
just build          # cargo build --workspace
```

### Run the worker (a live strategy)

```bash
# Regenerate SDK stubs (offline-safe)
just sdk-generate

# Run a grid strategy against the mock venue
cargo run -p longtrader-worker -- --config config.toml
```

Minimal `config.toml`:

```toml
backend = "api"                               # mock | api
endpoint = "http://127.0.0.1:8810"            # embedded longtrader-terminal; standalone longtrader-api serve uses :8080
api_token_file = "/run/secrets/longtrader_token"
listen_endpoint = "127.0.0.1:9000"          # WorkerSessionService + proxies (optional)

[strategy]
type = "simple_grid"
[strategy.params]
symbol = "BTCUSDT"
exchange_id = "mock"
lower_price = "90000"
upper_price = "110000"
num_levels = 10
qty_per_level = "0.001"
```

The token is loaded from `api_token_file` only (trimmed, never logged) and sent as `Authorization: Bearer <token>` over `hpx` with `rustls`.

### Drive it from the CLI

```bash
cargo run -p longtrader-cli -- --help
longtrader health                    # health check
longtrader symbols --venue mock      # list tradeable symbols
longtrader candles BTCUSDT --timeframe M1 --limit 100
longtrader buy BTCUSDT 0.001 --price 95000
longtrader stream --topics MARKET_LITE,TRADING   # live updates (Ctrl+C to stop)
```

### Or from an SDK (same lifecycle in every language)

```python
from longtrader_sdk import Session
s = Session.attach("http://127.0.0.1:8080", token="YOUR_TERMINAL_TOKEN")
s.start_heartbeat()
snap = s.reconcile_state()
print(s.session_id, s.state, snap.snapshot_sequence)
s.close()
```

```ts
import { Session } from "@longcipher/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();
```

Attach → heartbeat → reconcile → gate to `ACTIVE`. This is the contract every language implements identically.

---

## CLI (`longtrader-cli`)

A command-line client for the LongTrader Terminal API. Binary name: `longtrader`.

```bash
# Global flags
--endpoint <url>      # Terminal API endpoint (default: http://127.0.0.1:8810)
--token <token>       # Bearer token (also read from $LONGTRADER_TOKEN)
--venue <name>        # Venue name (default: mock)
--format <format>     # Output format: table, json (default: table)

# Commands
longtrader health                                    # Health check
longtrader venues                                    # List connected venues
longtrader symbols --venue mock                      # List tradeable symbols
longtrader candles <SYMBOL> --timeframe M1 --limit 100 # OHLCV candles
longtrader book <SYMBOL> --depth 10                  # Order book snapshot
longtrader search <QUERY> --limit 50                 # Search symbols
longtrader account                                   # Account balances
longtrader positions                                 # Open positions
longtrader orders --symbol <SYMBOL>                  # Open orders
longtrader history --limit 100                       # Order history
longtrader buy <SYMBOL> <QTY> --price <PRICE>        # Place buy order (limit; omit --price for market)
longtrader sell <SYMBOL> <QTY> --price <PRICE>       # Place sell order
longtrader cancel <ORDER_ID>                         # Cancel order
longtrader close <POSITION_ID>                       # Close position
longtrader stream --topics MARKET_LITE,TRADING       # Stream live updates
```

> `buy`/`sell` place a **limit** order when `--price` is given and a **market** order when it is omitted. Order-by-id and strategy-control RPCs are available in the contract; the CLI surface covers the market/trading read-write lifecycle end to end.

Timeframes: `M1`, `M5`, `M15`, `M30`, `H1`, `H4`, `D1`, `W1`.
Topics: `MARKET_LITE`, `MARKET_HEAVY`, `TRADING`, `RUNTIME`, `FUNDING`, `DERIVATIVES`.

Output is script-friendly: `--format json` emits pipeable JSON on **stdout**, with errors and hints on **stderr** and a non-zero exit code on failure.

---

## Strategies

Each strategy under `bin/longtrader-worker/src/strategies/<name>/` ships its own `README.md` (and `README.zh.md`) with parameters, risk notes, and an example config. Select one via `strategy.type`:

| Category | Strategies |
|---|---|
| Grid / Market Making | `simple_grid`, `boll_grid`, `skewed_grid`, `grid_strike`, `fixed_maker`, `cross_maker`, `cross_depth_maker`, `cross_fixed_maker`, `pure_market_making`, `pmm_dynamic`, `avellaneda_mm_v2`, `glft_mm`, `simplified_glft_mm`, `obi_mm`, `basis_mm`, `apt_mm`, `queue_mm`, `perpetual_mm`, `cross_exchange_mm`, `liquidity_mining`, `dman_v3` |
| Trend Following | `ema_cross`, `supertrend`, `adx_trend`, `ichimoku`, `darvas_box`, `dual_thrust`, `macd_bb`, `bb_keltner_squeeze` |
| Mean Reversion & Momentum | `mean_reversion`, `momentum_factor`, `cvd_divergence`, `bollinger_v2` |
| Arbitrage | `amm_arb`, `spot_perp_arb`, `stat_arb` |
| Hedging | `hedge`, `hedge_grid` |
| Execution Algorithms | `twap_executor`, `vwap_executor`, `dca_executor` |
| Portfolio & Rebalancing | `rebalance`, `market_cap`, `dca_scheduler`, `dca` |
| Risk & Operations | `sentinel`, `autoborrow`, `balance_align`, `convert`, `deposit_transfer` |
| Signals & Analytics | `irr`, `nav_recorder`, `premium_monitor`, `xfunding_lite` |
| Simulation & Testing | `random_entry` |

All strategies are original LongTrader implementations and depend only on `ports::{TradingGateway, MarketDataSource}` (and, where noted, the extended `FundingRateSource` / `VenueOpInvoker` / `WalletGateway` caps). Transport selection lives in `adapters/`. See [docs/strategy-author-guide.md](docs/strategy-author-guide.md) to write your own.

`dca` is the historical alias of `dca_scheduler`; both names are accepted so existing configs keep working.

### Pre-trade risk gate

Every order a strategy submits passes through an optional pre-trade gate before it reaches a venue. It is configured under `[risk]` and is **off by default** — an absent or empty section is a pass-through with no allocation on the hot path.

```toml
[risk]
max_order_notional = "50000"   # reject one order priced above this
max_order_qty = "1"            # reject one order sized above this
max_net_qty_per_symbol = "5"   # reject when a symbol's resting exposure would exceed this
max_open_orders = 200          # reject once this many resting orders are outstanding
max_orders_per_minute = 120    # reject once the submission rate exceeds this
```

A rejection is returned to the strategy as a `PortError` and never reaches the venue; cancel and close paths are always allowed so a kill switch can never be blocked by the gate. See [docs/risk-controls.md](docs/risk-controls.md).

---

## Development

```bash
just format     # rumdl fmt + cargo sort + cargo +nightly fmt
just fix        # rumdl --fix + clippy --fix
just mutation   # cargo mutants (focused on library crates)
just ci         # lint + test + build (mirrors CI)
just ci-all     # the above plus every SDK lint + test (needs Go/Node/Python)
```

Contract toolchain:

```bash
just proto-lint     # buf lint on proto/
just proto-breaking # breaking check vs main
just sdk-generate   # local stub generation (offline-safe via scripts/gen-proto.sh)
```

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. See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## Documentation

- [Architecture]docs/architecture.md — layers, control-plane state machine, envelope framing.
- [Getting Started]docs/getting-started.md — install, configure, run your first strategy.
- [Bare Protocol Guide]docs/bare-protocol-guide.md — ConnectRPC wire format, auth, and streaming for non-SDK clients.
- [Strategy Author Guide]docs/strategy-author-guide.md — build and register a portable strategy.
- [Contract Style Guide]docs/contract-style-guide.md — enum/timestamp/pagination/money/error conventions.
- [Risk Controls]docs/risk-controls.md — the pre-trade risk gate: limits, exposure accounting and bypass rules.
- [FAQ]docs/faq.md — venues, tokens, upgrade path.

---

## Security

- No secrets are committed. Tokens are file-loaded (`api_token_file`) and compared with constant-time `subtle`.
- `proto/longtrader/exchange/v1/exchange_daemon.proto` was removed in this open-source release (legacy private daemon API). Use `longtrader.market/trading/stream/ops.v1` instead.
- Report vulnerabilities via GitHub Security Advisories; do not open public issues for sensitive reports. See [SECURITY.md]SECURITY.md.

---

## License

Apache-2.0 — see [LICENSE](LICENSE). SDK packages (`sdks/python`, `sdks/typescript`) are also Apache-2.0 unless noted otherwise.

## Acknowledgements

Built with `buffa`/`connectrpc`, `hpx`, `tokio`, `rust_decimal`, and `buf`.