miniqmt-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# miniqmt-cli: Drive miniQMT / xtquant from the Command Line

## Access Policy — read first

**All programmatic access to the trading daemon MUST go through `miniqmt-cli`.** Direct HTTP calls to `http://127.0.0.1:8765/...` are no longer a supported integration surface — the URL space, payload shapes, and error semantics are internal implementation details and may change without notice.

Reasons:

- **One source of truth.** The CLI's command set is the only documented API. The HTTP routes underneath exist solely to let the CLI talk to the daemon over an SSH tunnel; their paths are unstable.
- **Drift kills callers.** When a parallel HTTP reference existed, a polling agent followed a stale `/positions` / `/orders` / `/trades` (unprefixed) path and silently 404'd for hours. The CLI shields callers from this class of bug.
- **Safety pipeline.** The CLI carries the masking, idempotency client_req_id generation, and `--confirm-live` handshake conventions. Bypassing it weakens those guarantees even though the daemon enforces most of them.

Callers from non-Python runtimes should wrap the CLI as a subprocess (`subprocess.run(["miniqmt-cli", "account", "asset", "--account", "main", "--format", "json"], capture_output=True)`) rather than constructing HTTP requests by hand. SSE consumers should use `miniqmt-cli stream tick|kline|order ...` and parse its stdout, not subscribe to `/stream/*` directly.

If you're an agent on a different host than the daemon, configure remote mode in `~/.miniqmt_cli/client.toml`:

```toml
[client]
mode = "remote"
server_url = "http://127.0.0.1:8765"   # the daemon, via SSH tunnel
```

Then bring up the tunnel (see [SSH Tunnel](#ssh-tunnel) below). The CLI then works transparently — no proxy config needed.

## Architecture

Mac CLI (Click) --> SSH tunnel --> Windows FastAPI daemon (port 8765) --> xtquant/miniQMT

- **Client** (Mac): `~/.miniqmt_cli/client.toml` -- sends HTTP requests through an SSH tunnel
- **Server** (Windows): `~/.miniqmt_cli/server.toml` -- FastAPI daemon wrapping xtquant, runs as a Scheduled Task
- Communication: all commands hit `http://127.0.0.1:8765` via `ssh -N -L 8765:127.0.0.1:8765 <host>`

## Prerequisites

Before running any command, verify:

1. **SSH tunnel is up** -- without it, all commands fail with "cannot reach daemon"
2. **Daemon is running** on Windows -- check with `miniqmt-cli health`
3. **miniQMT client is open** on Windows -- required for xtquant to connect to the broker

### `/health` response shape

Two independent top-level blocks. There is **no** flat `state` enum — callers
compose decisions from the structured fields. (The old composite strings like
`daemon_up_no_trader` mixed two unrelated concerns into one name and have
been removed.)

```json
{
  "daemon": {
    "state": "up",              // up | degraded
    "xtquant_loaded": true,
    "xtquant_error": "..."      // present only when state == degraded
  },
  "accounts": {
    "main": {
      "trader": {
        "state": "alive",       // never_connected | alive | lost
        "last_connect_at": "2026-05-13T09:30:01Z",
        "last_disconnect_at": null
      },
      "risk_breaker": "ok",     // ok | tripped
      "baseline": "captured"    // captured | pending
    }
  }
}
```

**Scope of each field:**

- `daemon.state` is purely process-local: this Python process is up + xtquant
  module loaded. It says nothing about miniQMT or the broker.
- `accounts.<name>.trader.state` reflects what the daemon **last heard** on
  the xtquant SDK channel — `alive` after a successful login, `lost` after
  xtquant fires `on_disconnected`. The daemon cannot independently probe
  miniQMT's GUI or broker connectivity, so a `lost` flag is a positive
  signal (SDK told us the channel dropped), but a stale `alive` flag is
  not a guarantee the channel is currently up. The only definitive
  liveness probe is to run an account command — a real broker failure
  surfaces as `trader.connect failed rc=...` or
  `trader.subscribe failed rc=...`.
- `risk_breaker` and `baseline` are computed from the daemon's risk manager.
- When the daemon was started with `serve --dry-run`, the `daemon` block adds `"dry_run": true` and `xtquant_loaded` is forced to `false` (xtquant is never touched in that mode). All account commands raise; this mode is for offline development only.

**Reading rules of thumb:**

| You want to know… | Read… |
|---|---|
| Daemon process alive? | `daemon.state == "up"` |
| xtquant loadable? | `daemon.xtquant_loaded == true` |
| Trader session for an account dropped? | `accounts.<name>.trader.state == "lost"` |
| When did it drop / when did it last connect? | `accounts.<name>.trader.last_disconnect_at` / `last_connect_at` |
| Account safe to send orders? | `daemon.state == "up"` AND `accounts.<name>.trader.state == "alive"` AND `accounts.<name>.risk_breaker == "ok"` AND `accounts.<name>.baseline == "captured"` |
| Account has never tried to log in (fresh daemon)? | `accounts.<name>.trader.state == "never_connected"` — run any `account` command to trigger lazy login |

`miniqmt-cli health` prints a human summary of this body. Exit code rules:

- **Exit 1** when any of these are true: daemon unreachable (`cannot reach daemon …`); `daemon.state != "up"` (e.g. xtquant failed to load); any `accounts.<name>.trader.state == "lost"`; any `accounts.<name>.risk_breaker == "tripped"`; any `accounts.<name>.baseline == "pending"` while that account's trader is `alive`.
- **Exit 0** otherwise. In particular, a fresh daemon where every account is `never_connected` exits 0 — that's the normal lazy-load state, not an error.

## Global Options

```bash
miniqmt-cli [--format table|json|csv] [--config <path>] <command>
```

Default format comes from `client.toml`; override per-call with `--format`.

## Commands Reference

### Market Data

```bash
# List sectors (e.g. 沪深A股, 上证50)
miniqmt-cli sector list

# List instruments in a sector
miniqmt-cli instrument list --sector "沪深A股"
miniqmt-cli instrument list --limit 10

From oopslink/trading-skills, MIT.

More from oopslink/trading-skills