keys.json 字段¶

{
  "version": 1,        // 目前固定 1；未来改 schema 会 bump
  "keys": [
    { /* KeyRecord */ }
  ]
}

KeyRecord 字段¶

字段	类型	必填	说明
`id`	string	✓	人看的名字，keys.json 内唯一；audit 里的 `key_id`
`hash`	string	✓	明文 SHA-256 hex
`scopes`	`["qot:read", "acc:read", ...]`	✓	能干啥
`limits`	object	—（空 = 不限）	限额，见下表
`allowed_machines`	`[fp, ...]` / null	—	null = 不绑；`[]` = 冻结；`[fp1,fp2]` = 白名单
`created_at`	RFC3339 timestamp	✓	生成时间
`expires_at`	RFC3339 / null	—	null = 不过期
`note`	string	—	备注

limits 字段¶

字段	类型	说明
`allowed_markets`	`["HK","US","CN","HKCC",...]` / null	市场白名单
`allowed_symbols`	`["HK.00700","US.AAPL"]` / null	品种白名单
`allowed_trd_sides`	`["BUY","SELL","SELL_SHORT","BUY_BACK"]` / null	方向白名单
`max_order_value`	float / null	单笔上限（qty × price，本币金额）
`max_daily_value`	float / null	日累计上限（UTC 日滚）
`max_orders_per_minute`	u32 / null	速率（60 秒滑动窗口）
`hours_window`	"HH:MM-HH:MM" / null	时段（本地时区，跨午夜用 `22:00-04:00` 表示）

null / 不写 = 不限。

scope 字符串¶

scope	能干啥
`qot:read`	行情只读 + 订阅
`acc:read`	账户只读
`trade:simulate`	模拟交易写
`trade:real`	真实交易写
`trade:unlock`	MCP `futu_unlock_trade` 工具用（v1.4+）

示例¶

最小只读¶

{
  "id": "research",
  "hash": "a1b2...",
  "scopes": ["qot:read"],
  "created_at": "2026-04-15T10:00:00Z"
}

紧限额的模拟交易¶

{
  "id": "sim-bot",
  "hash": "c4d5...",
  "scopes": ["qot:read", "acc:read", "trade:simulate"],
  "limits": {
    "allowed_markets": ["HK"],
    "allowed_symbols": ["HK.00700", "HK.09988"],
    "max_order_value": 100000,
    "max_daily_value": 500000,
    "max_orders_per_minute": 3,
    "hours_window": "09:30-16:00",
    "allowed_trd_sides": ["SELL"]
  },
  "allowed_machines": ["fp_bot_host_abc123"],
  "created_at": "2026-04-15T10:00:00Z",
  "expires_at": "2026-05-15T10:00:00Z",
  "note": "simulate 卖出止盈 bot"
}

操作¶

所有修改都走 futucli，不要手动编辑文件（原子写避免并发损坏；SHA-256 hash 手写容易错）：

futucli gen-key ...               # 新增
futucli list-keys                 # 列表
futucli revoke-key <id>           # 删除
futucli bind-key <id> ...         # 改 allowed_machines

改完 kill -HUP 让网关 / MCP 热重载。