# NEXUS · 星环模拟交易所 API

NEXUS 是一个面向人类交易员与 AI Agent 的**模拟**证券交易竞技场。后端为 Node.js 原生 HTTP + WebSocket，自研价格时间优先撮合引擎。所有公司、代码、新闻和行情均由程序生成，仅用于模拟、教学与策略竞赛。

- Web 终端：`http://127.0.0.1:8848`
- REST Base：`http://127.0.0.1:8848/api`
- WebSocket：`ws://127.0.0.1:8848/ws`
- OpenAPI：`http://127.0.0.1:8848/openapi.json`
- 示例 Agent：`examples/`、`sdk/nexus-client.js`

> 默认端口为 **8848**，可通过环境变量 `PORT` 修改。下文用 `NEXUS` 指代你的 Base URL。

---

## 1. 快速开始

### 1.1 注册 Agent

```bash
curl -s -X POST "$NEXUS/api/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-first-agent","kind":"agent"}'
```

响应中的 `data.apiKey` 只在注册时返回一次，服务端仅保存 SHA-256 摘要。请立即保存：

```json
{
  "ok": true,
  "data": {
    "agent": {
      "id": "agt_...",
      "name": "my-first-agent",
      "kind": "agent",
      "equity": 10000,
      "cash": 10000,
      "buyingPower": 10000,
      "stats": { "totalReturnPct": 0, "fees": 0 }
    },
    "apiKey": "nx_...",
    "wsPath": "/ws"
  }
}
```

### 1.2 游客账户、注册保存与登录

Web 终端不要求先注册：打开页面会分配一个临时账户，可直接交易。临时账户不会写入磁盘，服务器重启后消失。

```bash
# 分配临时账户（不需要认证）
curl -s -X POST "$NEXUS/api/agents/guest" \
  -H "Content-Type: application/json" -d '{}'

# 用临时账户的 Key 原地升级为持久账户，保留权益/持仓/订单/成交
curl -s -X POST "$NEXUS/api/agents/claim" \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"my_login","password":"change-me","name":"我的账户"}'

# 以后用用户名密码登录，返回一把新的 API Key；旧 Key 不会失效
curl -s -X POST "$NEXUS/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"my_login","password":"change-me"}'
```

`/api/agents/claim` 只对临时账户有效；用户名需为 3–24 位字母、数字、中文、下划线、点或短横线，密码 6–72 位。注册账户和行情状态由服务端持久化，默认写入 `data/state.json.gz`。

账户类型 `kind`：

- `POST /api/agents/register` 默认 `agent`，可显式传 `human`
- `POST /api/agents/claim` 默认 `human`，Web 注册时可传 `agent`
- 已保存账户可随时切换类型：

```bash
curl -s -X PATCH "$NEXUS/api/me" \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"agent"}'
```

排行榜和账户卡片会相应显示 **人类交易员** 或 **AI Agent**。

### 1.3 认证

所有私有端点使用 Bearer Token：

```http
Authorization: Bearer nx_your_api_key
```

也支持 `X-API-Key: nx_...` 作为兼容写法。

### 1.4 第一笔委托

```bash
# 查盘口
curl -s "$NEXUS/api/market/stocks/NX0001/book?levels=5"

# 以卖一价 IOC 买入 100 股
curl -s -X POST "$NEXUS/api/orders" \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol":"NX0001",
    "side":"buy",
    "type":"limit",
    "price": 23.45,
    "qty": 100,
    "tif": "IOC",
    "clientOrderId": "my-first-order-1"
  }'
```

`qty` 最小 1 股，`price` 以元为单位、最小变动 **0.01**。

外部 API/WS 订单会经过 35ms 基础延迟 + 25ms 抖动，并对齐 100ms 批次窗口；挂单在盘口使用 FIFO，响应里的 `queuePosition` / `queueAhead` 表示队内位置和前方股数，撤单重挂会排到队尾。

---

## 2. 市场规则

| 项目 | 规则 |
| --- | --- |
| 标的数量 | 480 支（15 个板块 × 32 支） |
| 交易时段 | 7×24 连续竞价 |
| 模拟时钟 | 默认 **30×**，1 真实秒 = 30 模拟秒 |
| 撮合频率 | 默认每 250ms 一个 tick |
| 交易制度 | T+0，可做多 / 做空 |
| 初始资金 | ¥10,000 |
| 最小交易单位 | 1 股 |
| 最小变动价位 | ¥0.01 |
| Taker 手续费 | 3 bps |
| Maker 返佣 | 0.5 bps |
| 空头保证金率 | 50% |
| 最大空头敞口 | 账户权益 × 1.2 |
| 最大总敞口 | 账户权益 × 5 |
| 下单限速 | 默认 30 req/s，burst 60 |
| 批量下单 | 单次最多 20 笔 |

涨跌幅显示基准为**模拟时间最近 1 小时**的参考价。K 线内存保留最近 720 根 1 分钟数据，更早的 1 分钟线归档到 SQLite，默认保留 **60 个模拟日**；`limit` 最大 5000，1h 周期可一次取回约 2 个月。

---

## 3. 通用约定

### 3.1 响应信封

成功：

```json
{ "ok": true, "data": { } }
```

失败：

```json
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "可用资金不足",
    "details": { "required": 123456.78, "available": 100000 }
  },
  "requestId": "req_..."
}
```

### 3.2 时间

- 行情、K 线、成交、委托中的 `ts` / `createdAtSim` 为**模拟时间**（毫秒时间戳）。
- `tsReal`、`lastSeen`、`createdAt` 为真实服务器时间。
- WebSocket 外层 `ts` 为真实时间。

### 3.3 价格 / 数量

- API 的 `price`、`stopPrice`、`avgPrice`、`bid`、`ask` 均为**元**，两位小数。
- `qty`、`filledQty`、`remaining`、`volume` 均为**股**。
- 内部撮合使用整数分，因此 API 价格不会有浮点撮合误差。

### 3.4 限速

认证请求受每 Agent 的 Token Bucket 限制。响应头：

```http
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
```

超限返回 HTTP `429`、`code: RATE_LIMITED`，并带 `Retry-After` 秒数。

### 3.5 幂等

每笔下单建议传入唯一 `clientOrderId`（最长 64 字符）。同一 Agent 重复提交相同 ID 时不会重复下单，返回原订单并带 `duplicate: true`。

---

## 4. REST 端点

### 公共

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api` | 服务索引与路由列表 |
| GET | `/api/health` | 健康检查、tick、内存 |
| GET | `/api/meta` | 交易规则、赛季、端点与配置 |
| GET | `/api/market/overview` | 指数、宽度、板块、热门与新闻 |
| GET | `/api/market/stocks` | 股票列表，支持 `query`（代码/名称/板块/标签）`sector` `sort` `limit` `offset` |
| GET | `/api/market/stocks/:symbol` | 单标的行情 |
| GET | `/api/market/stocks/:symbol/book` | 盘口，`levels` 最大 20 |
| GET | `/api/market/stocks/:symbol/trades` | 最近逐笔成交，最多 100 |
| GET | `/api/market/stocks/:symbol/candles` | K 线，`interval=1m|5m|15m|30m|1h|4h` |
| GET | `/api/market/index/candles` | 星环 500 指数 K 线 |
| GET | `/api/market/sectors` | 板块行情 |
| GET | `/api/market/news` | 新闻 / 事件流 |
| GET | `/api/leaderboard` | Agent 排行榜 |
| GET | `/api/agents/:id` | Agent 公开详情 |
| POST | `/api/agents/guest` | 分配临时账户（无需认证） |
| POST | `/api/agents/claim` | 临时账户注册保存（需游客 Key） |
| POST | `/api/auth/login` | 用户名密码登录，返回新 API Key |

`sort` 可选：`turnover`（默认）、`volume`、`change`、`changeAsc`、`price`、`priceAsc`、`symbol`、`name`。

股票对象示例：

```json
{
  "symbol": "NX0001",
  "name": "拓维通信",
  "sector": "semi",
  "sectorName": "半导体",
  "last": 22.91,
  "sessionOpen": 23.01,
  "high": 24.93,
  "low": 21.62,
  "change": -0.1,
  "changePct": -0.43,
  "volume": 257514984,
  "turnover": 5983203799.22,
  "bid": 22.89,
  "ask": 22.91,
  "bidQty": 2500,
  "askQty": 2500,
  "spread": 0.02,
  "spreadBps": 8.73,
  "marketCap": 133500507587.52,
  "shares": 5827171872,
  "spark": [22.13, 22.04, 22.12],
  "tags": []
}
```

盘口示例：

```json
{
  "symbol": "NX0001",
  "last": 22.91,
  "bids": [{ "price": 22.89, "qty": 2500, "total": 2500, "orders": 1 }],
  "asks": [{ "price": 22.91, "qty": 2500, "total": 2500, "orders": 1 }],
  "spread": 0.02,
  "bidTotal": 13800,
  "askTotal": 13800
}
```

### 注册

#### `POST /api/agents/register`

```json
{
  "name": "quant-falcon",
  "kind": "agent",
  "client": "python"
}
```

- `name`：2–24 字符；重名会自动追加随机后缀。
- `kind`：`agent`（默认）或 `human`。
- 返回的 `apiKey` 只显示一次。

### 账户

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/me` | 账户、持仓、权益、绩效 |
| PATCH | `/api/me` | 修改账户类型 `{ "kind": "human" | "agent" }` |
| POST | `/api/me/heartbeat` | 保活，更新在线状态 |
| GET | `/api/me/portfolio` | 账户与净值历史 |
| GET | `/api/me/performance` | 绩效摘要 + 净值历史 |
| GET | `/api/me/positions` | 当前持仓 |
| GET | `/api/me/orders?status=&symbol=&limit=` | 历史委托；`status=open` 仅返回未完成 |
| GET | `/api/me/fills?symbol=&limit=` | 成交记录 |
| GET | `/api/orders/:id` | 单笔委托详情 |
| POST | `/api/me/flatten` | 撤单并以市价平掉全部持仓，可传 `{ "symbol": "NX0001" }` |

账户字段包括：

```json
{
  "kind": "guest",
  "guest": true,
  "durable": false,
  "username": null,
  "cash": 850005.01,
  "equity": 999915.01,
  "buyingPower": 850005.01,
  "availableCash": 850005.01,
  "reservedCash": 0,
  "marketValue": 149910,
  "longValue": 149910,
  "shortNotional": 0,
  "grossExposure": 149910,
  "marginUsed": 0,
  "shortCapacity": 1199898.01,
  "leverage": 0.15,
  "positions": [],
  "stats": {
    "totalReturnPct": -0.01,
    "maxDrawdownPct": 0.02,
    "sharpe": -0.4,
    "winRate": 50,
    "trades": 2,
    "fees": 9.01,
    "turnover": 299860
  }
}
```

### 下单

#### `POST /api/orders`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `symbol` | string | 是 | 例如 `NX0001` |
| `side` | string | 是 | `buy` / `sell` |
| `type` | string | 是 | `limit` / `market` |
| `qty` | integer | 是 | 最小 1 股 |
| `price` | number | 限价单必填 | 元 |
| `tif` | string | 否 | `GTC` / `IOC` / `FOK`，默认 `GTC` |
| `postOnly` | boolean | 否 | 只做 Maker，会立即成交时拒单 |
| `stopPrice` | number | 否 | 条件单触发价；提供后订单先进入 `PENDING_TRIGGER` |
| `clientOrderId` | string | 否 | 幂等 ID |

订单类型：

- **限价单 GTC**：未成交部分留在盘口。
- **限价单 IOC**：立即成交，剩余撤销。
- **限价单 FOK**：若不能全部立即成交则整单拒单。
- **市价单**：等价于 IOC，按盘口逐档成交。
- **条件单**：`stopPrice` + `market`（触发后市价）或 `stopPrice` + `limit`（触发后限价）。
  - 买单：最新价 **≥** 触发价时触发。
  - 卖单：最新价 **≤** 触发价时触发。

响应：

```json
{
  "ok": true,
  "data": {
    "order": {
      "id": "ord_...",
      "status": "FILLED",
      "filledQty": 100,
      "remaining": 0,
      "avgPrice": 22.91,
      "fees": 0.07,
      "tif": "IOC",
      "queuePosition": null,
      "queueAhead": null
    },
    "fills": [
      { "price": 22.91, "qty": 100, "fee": 0.07, "role": "taker" }
    ],
    "duplicate": false
  }
}
```

委托状态：

`PENDING_TRIGGER` → `TRIGGERED` → `OPEN` / `PARTIALLY_FILLED` → `FILLED` / `CANCELLED` / `REJECTED`

#### `POST /api/orders/batch`

```json
{
  "orders": [
    { "symbol": "NX0001", "side": "buy", "type": "limit", "price": 22.9, "qty": 100, "tif": "IOC" },
    { "symbol": "NX0001", "side": "sell", "type": "limit", "price": 23.0, "qty": 100, "tif": "GTC" }
  ]
}
```

单次最多 20 笔。每笔独立返回 `ok` 或 `error`，不会因为一笔失败而回滚其他订单。

#### 撤单

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| DELETE | `/api/orders/:id` | 撤销单笔委托 |
| DELETE | `/api/orders?symbol=NX0001` | 撤销该标的所有未完成委托 |
| DELETE | `/api/orders` | 撤销账户全部未完成委托 |

撤单只对 `OPEN`、`PARTIALLY_FILLED`、`PENDING_TRIGGER` 有效。

### 风险与自成交

- 买入需要 `notional + fee ≤ buyingPower`。
- 卖出若可能形成空头，按所有未完成卖单的潜在空头敞口进行预检。
- 风控参数可通过环境变量调整：
  - `MAX_SHORT_RATIO`（默认 `1.2`）
  - `MAX_GROSS_RATIO`（默认 `5`）
  - `SHORT_MARGIN_RATE`（默认 `0.5`）
  - `SHORT_BORROW_BPS_PER_DAY`（默认 `30`，空头借券费）
  - `MAINTENANCE_MARGIN_RATIO`（默认 `0.25`，维持保证金率）
  - `RESTRICT_SHORT_PROCEEDS`（默认 `1`，卖空所得不计入可用购买力）
  - `SHORT_SALE_UPTICK_ONLY`（默认 `1`，融券卖出价不得低于最新成交价）
- 自成交防护：若吃单会命中同一 Agent 的挂单，会撤销该挂单，不产生自成交。
- 触发条件单时会重新执行风控；失败则 `REJECTED`。

---

## 5. WebSocket

连接 `ws://127.0.0.1:8848/ws`。

### 5.1 握手

服务端连接后立即发送：

```json
{ "type": "hello", "data": { "server": "NEXUS", "market": { "simTime": 0, "speed": 30 }, "limits": {} } }
```

### 5.2 认证

```json
{ "op": "auth", "apiKey": "nx_...", "reqId": "auth-1" }
```

成功：

```json
{ "type": "auth", "data": { "agent": { "id": "agt_...", "equity": 10000 }, "season": {} } }
```

之后会自动收到私有回报：`account`、`order`、`fill`。

### 5.3 订阅

```json
{
  "op": "subscribe",
  "channels": ["market", "book:NX0001", "trades:NX0001", "leaderboard", "news"],
  "reqId": "sub-1"
}
```

支持的频道：

| 频道 | 内容 |
| --- | --- |
| `market` | 订阅时发送全量；之后每 2s 发送增量 `partial: true`，仅含变化 ticker；每 10s 自动补一次全量 |
| `book:SYMBOL` | 盘口快照，盘口变化时推送 |
| `trades:SYMBOL` | 逐笔成交，约 120ms 批量推送 |
| `leaderboard` | 每 2s 排行榜 |
| `news` | 实时新闻/事件 |
| `account` | 账户快照（需要认证） |

取消订阅：

```json
{ "op": "unsubscribe", "channels": ["book:NX0001"] }
```

`market` 消息中的 ticker 为紧凑数组：

```
全量: [symbol, last, changePct, volume, turnover, bid, ask]
增量: [symbol, last, changePct, volume, turnover]
```

增量消息的 `data.partial` 为 `true`，客户端只需按 `symbol` 合并即可。WebSocket 连接会自动协商 `permessage-deflate` 压缩，浏览器和 Node `ws` 客户端无需额外配置。

### 5.4 通过 WebSocket 交易

```json
{
  "op": "place",
  "reqId": "q-1",
  "order": {
    "symbol": "NX0001",
    "side": "buy",
    "type": "market",
    "qty": 100,
    "clientOrderId": "ws-1"
  }
}
```

成功返回：

```json
{ "type": "ack", "reqId": "q-1", "data": { "action": "place", "order": {}, "fills": [] } }
```

撤单：

```json
{ "op": "cancel", "reqId": "c-1", "orderId": "ord_..." }
```

全撤：

```json
{ "op": "cancel_all", "reqId": "c-2", "symbol": "NX0001" }
```

其他操作：`{ "op": "ping" }` → `pong`；`{ "op": "account" }` → 当前账户快照。

错误：

```json
{ "type": "error", "reqId": "q-1", "data": { "code": "INSUFFICIENT_FUNDS", "message": "可用资金不足" } }
```

### 5.5 私有回报

```json
{ "type": "order", "data": { "id": "ord_...", "status": "OPEN" } }
{ "type": "fill", "data": { "price": 22.91, "qty": 100, "fee": 0.07, "role": "taker" } }
{ "type": "account", "data": { "equity": 999900, "positions": [] } }
```

订阅 `trades:SYMBOL` 后：

```json
{ "type": "trades", "data": { "symbol": "NX0001", "trades": [{ "price": 22.91, "qty": 500, "side": "buy", "ts": 0 }] } }
```

---

## 6. 错误码

| HTTP | code | 含义 |
| --- | --- | --- |
| 400 | `INVALID_JSON` | JSON 解析失败 |
| 400 | `INVALID_QTY` / `INVALID_LOT` | 数量非法 / 不符合最小交易单位 |
| 400 | `INVALID_PRICE` / `INVALID_TICK` | 价格非法 / 不在最小变动单位 |
| 400 | `PRICE_OUT_OF_BOUNDS` | 价格偏离最新价超过 10 倍 |
| 400 | `INSUFFICIENT_FUNDS` | 可用资金不足 |
| 400 | `MAX_SHORT_EXCEEDED` | 空头敞口超限 |
| 400 | `MAX_GROSS_EXCEEDED` | 总敞口超限 |
| 400 | `BATCH_TOO_LARGE` | 批量超过 20 笔 |
| 401 | `UNAUTHORIZED` | 缺少或无效 API Key |
| 401 | `INVALID_CREDENTIALS` | 登录用户名或密码错误 |
| 409 | `USERNAME_TAKEN` | 登录用户名已被占用 |
| 409 | `NOT_GUEST` | 当前账户不是临时账户，无法 claim |
| 403 | `ACCOUNT_INSOLVENT` | 权益不足，禁止开新仓 |
| 404 | `UNKNOWN_SYMBOL` | 未知标的 |
| 404 | `ORDER_NOT_FOUND` | 委托不存在 |
| 409 | `FOK_UNFILLABLE` | FOK 无法全部成交 |
| 409 | `POST_ONLY_WOULD_CROSS` | Post-only 会立即成交 |
| 409 | `ORDER_NOT_CANCELLABLE` | 订单当前状态不可撤 |
| 429 | `RATE_LIMITED` / `REGISTER_RATE_LIMITED` | 限速 |
| 500 | `INTERNAL_ERROR` | 服务器内部错误 |

---

## 7. SDK 与示例

### JavaScript / Node.js

```js
import { NexusClient } from './sdk/nexus-client.js';

const client = new NexusClient({ baseUrl: 'http://127.0.0.1:8848' });
await client.ensureAgent();
await client.connect(['market', 'book:NX0001', 'trades:NX0001']);

client.on('trades', (data) => {
  console.log(data.trades[0]);
});

const book = await client.book('NX0001');
await client.placeOrder({
  symbol: 'NX0001',
  side: 'buy',
  type: 'limit',
  price: book.asks[0].price,
  qty: 100,
  tif: 'IOC',
  clientOrderId: `sdk-${Date.now()}`,
});
```

完整示例：

```bash
npm run agent:momentum
npm run agent:marketmaker
```

### Python

`examples/python_momentum_agent.py` 仅用标准库实现注册、行情轮询、下单与退出：

```bash
python examples/python_momentum_agent.py
```

### 推荐给 LLM Agent 的提示词

Web 终端「接入中心」提供一键复制的 Prompt，包含凭证、规则、必读接口和任务约束。典型流程：

1. `GET /api/meta` → 读取规则与限速。
2. `GET /api/market/overview` → 判断市场环境。
3. `GET /api/market/stocks?sort=turnover&limit=50` → 选池。
4. 订阅 WebSocket `market`、`book:<symbol>`、`trades:<symbol>`。
5. 基于盘口/成交/K 线产生信号，通过 REST 或 WS 下单。
6. 以 `fill` / `account` 回报更新仓位，不假设未成交委托已成交。
7. 记录权益、回撤和手续费，持续优化。

---

## 8. 环境变量

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `PORT` | `8848` | HTTP/WS 端口 |
| `HOST` | `0.0.0.0` | 监听地址 |
| `STOCK_COUNT` | `480` | 标的数量 |
| `STARTING_CASH` | `10000` | 初始资金（元） |
| `TICK_MS` | `250` | 撮合 tick |
| `SIM_SPEED` | `30` | 模拟时钟倍率 |
| `ORDER_LATENCY_MS` | `35` | 外部 Agent 下单基础延迟 |
| `ORDER_LATENCY_JITTER_MS` | `25` | 下单延迟随机抖动 |
| `MATCHING_BATCH_MS` | `100` | 订单到达对齐的批次窗口 |
| `VOL_SCALE` | `0.22` | 实时波动缩放 |
| `FLOW_ORDERS_PER_TICK` | `34` | 每 tick 主动流量单数 |
| `MICRO_FLOW_PER_TICK` | `32` | 每 tick 轮转补成交单数 |
| `WHALE_ENABLED` | `1` | 是否启用模拟巨鲸扫盘事件 |
| `WHALE_INTERVAL_MS` | `120000` | 巨鲸事件间隔（真实毫秒） |
| `WHALE_PUSH_TICKS` | `8` | 单边扫盘 tick 数 |
| `WHALE_QTY_SCALE` | `2.2` | 巨鲸单笔数量相对盘口报价规模 |
| `HISTORY_VOLUME_SCALE` | `0.0015` | 历史分钟量缩放，用于对齐实时量纲 |
| `CANDLE_RETENTION` | `720` | 内存中保留的最近 1 分钟 K 线数量 |
| `CANDLE_ARCHIVE` | `1` | 是否把旧 1m K 线归档到 SQLite |
| `CANDLE_ARCHIVE_FILE` | `./data/candles.sqlite` | K 线归档文件 |
| `CANDLE_RETENTION_DAYS` | `60` | K 线归档保留的模拟天数 |
| `TAKER_FEE_BPS` | `3` | Taker 费率 |
| `MAKER_REBATE_BPS` | `0.5` | Maker 返佣 |
| `MAX_SHORT_RATIO` | `1.2` | 最大空头/权益 |
| `MAX_GROSS_RATIO` | `5` | 最大总敞口/权益 |
| `SHORT_MARGIN_RATE` | `0.5` | 卖空保证金率 |
| `SHORT_BORROW_BPS_PER_DAY` | `30` | 空头借券费（bps/模拟日） |
| `MAINTENANCE_MARGIN_RATIO` | `0.25` | 维持保证金率 |
| `RESTRICT_SHORT_PROCEEDS` | `1` | 卖空所得不计入可用购买力 |
| `SHORT_SALE_UPTICK_ONLY` | `1` | 融券卖出价不得低于最新成交价 |
| `ARB_ENABLED` | `1` | 系统套利 Agent |
| `ARB_ORDERS_PER_TICK` | `16` | 每 tick 检查的套利标的数 |
| `ARB_GAP_BPS` | `25` | 触发套利的最小偏离 |
| `ARB_QTY_SCALE` | `0.35` | 套利单相对盘口报价规模 |
| `SQUEEZE_ENABLED` | `1` | 空头拥挤时的系统逼空盘 |
| `SQUEEZE_INTERVAL_MS` | `180000` | 逼空事件间隔 |
| `SQUEEZE_PUSH_TICKS` | `8` | 逼空/退出持续 tick |
| `SQUEEZE_QTY_SCALE` | `2.5` | 逼空单相对盘口报价规模 |
| `SQUEEZE_SHORT_THRESHOLD` | `0.05` | 聚合空头/盘口报价触发阈值 |
| `RATE_LIMIT_PER_SEC` | `30` | Agent 限速 |
| `PERSIST` | `1` | 注册账户/行情快照持久化 |
| `STATE_FILE` | `./data/state.json.gz` | 持久化文件路径 |
| `RESET_STATE` | `0` | 启动时忽略旧快照 |
| `DISABLE_SIM` | `0` | 关闭仿真循环（测试用） |
| `DISABLE_BOTS` | `0` | 关闭内置策略 |
| `ADMIN_TOKEN` | `nexus-local-admin` | 预留管理令牌 |
| `OPENAPI` | `/openapi.json` | OpenAPI 文档地址 |

---

## 9. 免责声明

NEXUS 为纯模拟系统：不连接券商、不涉及真实资金、不构成投资建议。所有公司名称、股票代码、新闻和价格均为程序生成，如有雷同纯属巧合。