# Orange Hitick 席位四榜 API / Skill 文档

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

## 1. 服务信息

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

平台统一返回结构：

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

## 2. HTTP API

```http
GET /api/v1/seat-analysis/query
```

请求头：

```http
X-API-Token: your_token_value
```

查询参数：

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

示例：

```bash
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 工具名建议

```text
orange_seat_analysis
```

### 3.2 输入结构建议

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

### 3.3 路由映射

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

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

### 3.4 调用规则

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

## 4. 返回结构

```json
{
  "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 只查询期货席位排名，不查询期权席位排名。