Orange Hitick 席位四榜 API / Skill 文档

这份文档用于开发者手动接入，或让 Agent 按统一规则接入 Orange Hitick 的席位四榜查询能力。

1. 服务信息

HTTP 接口：GET /api/v1/seat-analysis/query
HTTP 鉴权方式：请求头 X-API-Token
返回包装：Orange Hitick 统一 ApiResponse
计费说明：成功查询后复用主观信号计费逻辑，模型名为 SeatAnalysis
数据说明：查询每日入库后的期货席位持仓事实表，不实时直连交易所

平台统一返回结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

2. HTTP API

GET /api/v1/seat-analysis/query

请求头：

X-API-Token: your_token_value

查询参数：

tradeDate：必填，支持 YYYY-MM-DD 或 YYYYMMDD
symbol：必填，期货合约代码，例如 m2609、IM2607
limit：可选，默认 20，最大 50

示例：

curl -sS 'https://api.hitick.top/api/v1/seat-analysis/query?tradeDate=2026-07-07&symbol=m2609&limit=20' \
  -H 'X-API-Token: your_token_value'

3. Agent 接入规范

如果给 Agent 使用，建议按下面的最小规则封装。

3.1 工具名建议

orange_seat_analysis

3.2 输入结构建议

{
  "tradeDate": "2026-07-07",
  "symbol": "m2609",
  "limit": 20
}

3.3 路由映射

将输入字段映射为查询参数，并调用：

GET /api/v1/seat-analysis/query?tradeDate={tradeDate}&symbol={symbol}&limit={limit}

3.4 调用规则

输入中不需要 action。
不需要传交易所，服务端会按 tradeDate + symbol 自动识别。
对外不暴露 source 或任何数据源字段。
调用成功后，结合四组榜单和 diff 字段总结席位方向与边际变化。

4. 返回结构

{
  "code": 0,
  "message": "success",
  "data": {
    "tradeDate": "2026-07-07",
    "symbol": "m2609",
    "exchange": "DCE",
    "notice": null,
    "lists": {
      "netBuy": [
        {"rankNo": 1, "brokerName": "高盛期货（代客）", "value": 127469, "diff": -425}
      ],
      "netSell": [
        {"rankNo": 1, "brokerName": "中粮期货（代客）", "value": 267143, "diff": 288}
      ],
      "longHolding": [
        {"rankNo": 1, "brokerName": "国泰君安（代客）", "value": 168029, "diff": 108}
      ],
      "shortHolding": [
        {"rankNo": 1, "brokerName": "中粮期货（代客）", "value": 301364, "diff": -332}
      ]
    }
  }
}

字段说明：

exchange：服务端自动识别出的交易所。
notice：不为空时通常表示该日期和标的暂无入库数据。
lists.netBuy：净买持仓榜。
lists.netSell：净卖持仓榜。
lists.longHolding：买方持仓榜。
lists.shortHolding：卖方持仓榜。
value：当前榜单数值。
diff：相对前一交易日的变化；大于 0 表示增加，小于 0 表示减少。

排序规则：

netBuy：按净买持仓从高到低。
netSell：按净卖持仓从高到低。
longHolding：按买方持仓从高到低。
shortHolding：按卖方持仓从高到低。

5. 席位分析方法论

查询席位四榜后，可以把榜单中的机构按常见客户群体与交易行为进行辅助归类，再结合净买、净卖、买方持仓、卖方持仓及其 diff 判断方向变化。以下分类是经验口径，用于解释席位行为，不应当作绝对标签。

5.1 外资席位

代表席位：乾坤期货、摩根大通等。
典型特征：在以进口为主的交易品种上交易胜率较高，常年倾向保持正向收益。
客户结构：席位主要客户群体以海外机构为主。
解读方式：外资席位在相关进口品种上持续净买、买方持仓增加，通常可作为中期偏多参考；持续净卖或卖方持仓增加，则需要关注海外资金对供需、汇率、进口利润等变量的定价变化。

5.2 机构席位

代表席位：国泰君安期货、海通期货、东证期货、永安期货、中信期货、中财期货等。
典型特征：客户群体通常具备专业调研能力和较强的市场观察能力，常年倾向保持正向收益。
研究优势：相对专业的宏观分析能力、产业调研能力和市场观察能力，对市场中长期方向有较高借鉴意义。
解读方式：当多家机构席位在同一方向上同步增仓，且净买或净卖变化连续扩大时，说明专业资金方向较一致；如果机构席位多空分歧较大，应降低单一席位信号权重，结合价格趋势和基本面验证。

5.3 散户席位

代表席位：东方财富期货、徽商期货、平安期货等。
典型特征：客户群体常见行为包括抄底摸顶、逆周期操作、亏损加仓，长期收益倾向偏弱。
市场影响：期货市场价格波动往往由供需失衡和资金推动共同形成；散户群体逆周期操作和亏损加仓，容易在特定阶段形成市场合力，使行情加速波动。
解读方式：散户席位集中净买但价格仍弱，或集中净卖但价格仍强时，可能提示趋势延续或加速；若散户方向与机构、外资方向相反，应优先关注机构和外资的持续性变化。

6. 使用建议

先看 netBuy 和 netSell 判断披露口径下的净方向，再看 longHolding 与 shortHolding 确认多空持仓来源。
进行席位归类时，优先按期货公司全称或常见全称匹配；交易所原始名称可能带有 （代客） 后缀，也可能省略“期货”二字，例如 国泰君安（代客）、东方财富（代客）、摩根大通（代客）。
对同一席位同时观察 value 和 diff：大持仓代表存量影响，连续正向 diff 代表边际推动。
单日席位变化容易受移仓、换月、套保和日内价格波动影响，重要结论应尽量结合连续多日变化。
该工具返回的是每日入库后的席位事实表，不是实时成交或实时持仓；分析结论应与行情、成交量、持仓量和基本面背景一起使用。

7. 异常情况

如果某天某标的没有入库数据，exchange 为 null，四组榜单为空，notice 返回可展示提示。
如果同一日期同一 symbol 匹配到多个交易所，接口会返回参数错误，提示使用更明确的合约代码。
v1 只查询期货席位排名，不查询期权席位排名。