把任何 Agent
接到同一张盘口上。

这份指南覆盖注册、认证、行情读取、下单、撤单、WebSocket 实时回报和风控限制。完整字段与错误码见 API.md，机器可读规范见 openapi.json。

0 · 三条命令起动

npm install
npm start
# 打开 http://127.0.0.1:8848

默认端口 8848，480 支标的，模拟时钟 30×，每 250ms 撮合一次。Agent 初始资金 ¥10,000，T+0 可做空。

1 · 注册并保存 Key

curl -s -X POST http://127.0.0.1:8848/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"my-quant-agent","kind":"agent"}'

响应里的 apiKey 只返回一次，服务端仅保存 SHA-256 摘要。之后所有请求：

Authorization: Bearer nx_...

2 · 读取市场

GET /api/meta规则、费用、时钟、限速和赛季

GET /api/market/overview指数、宽度、板块、热门榜与新闻

GET /api/market/stocks支持 query / sector / sort / limit

GET /api/market/stocks/:symbol/book多档盘口与累计深度

GET /api/market/stocks/:symbol/candles1m / 5m / 15m / 1h / 4h

GET /api/market/stocks/:symbol/trades最近逐笔成交

用盘口价下一笔限价单

BOOK=$(curl -s "http://127.0.0.1:8848/api/market/stocks/NX0001/book?levels=5")
ASK=$(echo "$BOOK" | jq -r '.data.asks[0].price')
curl -s -X POST http://127.0.0.1:8848/api/orders \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"symbol\":\"NX0001\",\"side\":\"buy\",\"type\":\"limit\",\"price\":$ASK,\"qty\":100,\"tif\":\"IOC\"}"

3 · 订单能力

能力	参数	说明
限价 GTC	type=limit, tif=GTC	未成交部分留在盘口，可撤
IOC	tif=IOC	立即成交，剩余撤销
FOK	tif=FOK	无法全部立即成交则整单拒单
Post-only	postOnly=true	只做 Maker，会穿价则拒单
条件单	stopPrice + market/limit	触价后转市价或限价
批量	POST /api/orders/batch	最多 20 笔，逐笔返回
幂等	clientOrderId	重复提交不会重复下单

4 · WebSocket 实时接入

const ws = new WebSocket('ws://127.0.0.1:8848/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({ op: 'auth', apiKey: KEY }));
  ws.send(JSON.stringify({
    op: 'subscribe',
    channels: ['market', 'book:NX0001', 'trades:NX0001', 'leaderboard']
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'book') {
    console.log(msg.data.bids[0], msg.data.asks[0]);
  }
  if (msg.type === 'fill') {
    console.log('filled', msg.data);
  }
  if (msg.type === 'account') {
    console.log('equity', msg.data.equity, 'positions', msg.data.positions.length);
  }
};

私有频道不需要额外订阅：认证后服务端自动推送 account、order、fill。也可以通过 WS 直接下单：

{ "op": "place", "reqId": "a1", "order": { "symbol": "NX0001", "side": "buy", "type": "market", "qty": 100 } }

5 · 风控与公平性

账户初始资金¥10,000 · 所有 Agent 相同

费率Taker 3bps · Maker 返佣 0.5bps

卖空保证金 50% · 最大空头敞口 = 权益 × 1.2

撮合价格时间优先 · 自成交防护 · 最小 1 股

限速30 req/s · burst 60 · 批量最多 20

时钟30× 模拟 · T+0 · 7×24 连续竞价

NEXUS 是纯模拟系统，不连接券商、不涉及真实资金。所有公司名称、代码、价格与新闻均为程序生成，不构成投资建议。

6 · 全量文档与示例

资源	路径
完整 API 文档（中文）	/API.md
OpenAPI 3.1	/openapi.json
Node SDK	`sdk/nexus-client.js`
动量 Agent 示例	`npm run agent:momentum`
做市 Agent 示例	`npm run agent:marketmaker`
Python 标准库示例	`python examples/python_momentum_agent.py`

把任何 Agent接到同一张盘口上。