Orange Hitick 基础数据 Skill 文档

这份文档用于开发者手动接入，或让 Agent 按统一规则接入 Orange Hitick 的基础数据服务。

1. 服务信息

平台接口前缀：/api/v1/basic-data
鉴权方式：请求头 X-API-Token
返回包装：Orange Hitick 统一 ApiResponse
当前服务编码：basic_data
当前服务名称：基础数据
计费说明：/catalog 不计费；/query/by-underlying、/query/by-expire、/query/by-symbol 成功返回后计费，扣费失败则接口直接返回错误

平台统一返回结构：

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

说明：

code = 0 表示平台调用成功
真正的基础数据结果放在 data 中
data 是上游接口返回结果的透传 JSON

2. 鉴权

所有请求都必须带：

X-API-Token: your_token_value

3. 接口列表

3.1 获取目录

GET /api/v1/basic-data/catalog

用途：

返回可查询的标的目录
不扣费

示例：

curl -sS 'https://api.hitick.top/api/v1/basic-data/catalog' \
  -H 'X-API-Token: your_token_value'

data 的核心结构：

{
  "catalog": {
    "cu2607": {
      "expiries": [
        {
          "expire_date": "20260624",
          "multipliers": [5]
        }
      ]
    }
  },
  "server_time_ms": 1780000000000
}

3.2 按标的查询

GET /api/v1/basic-data/query/by-underlying?underlying=cu2607

必填参数：

underlying：标的代码，例如 cu2607

示例：

curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-underlying?underlying=cu2607' \
  -H 'X-API-Token: your_token_value'

语义：

rows 第 1 行为标的行
后续行为该标的下全部到期日、全部合约乘数的期权行

3.3 按到期日查询

GET /api/v1/basic-data/query/by-expire?underlying=cu2607&expire=20260624

必填参数：

underlying：标的代码，例如 cu2607
expire：到期日，格式 yyyyMMdd，例如 20260624

示例：

curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-expire?underlying=cu2607&expire=20260624' \
  -H 'X-API-Token: your_token_value'

语义：

rows 第 1 行为标的行
后续行为该标的该到期日下全部合约乘数的期权行

3.4 按合约代码查询

GET /api/v1/basic-data/query/by-symbol?symbol=cu2607C78000

必填参数：

symbol：合约代码或标的代码

示例：

curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-symbol?symbol=cu2607C78000' \
  -H 'X-API-Token: your_token_value'

语义：

如果查的是期权，只返回 1 行期权行
如果查的是标的，只返回 1 行标的行

4. 查询返回结构

三个查询接口的 data 顶层结构一致：

{
  "found": true,
  "query_type": "by_symbol",
  "contract_count": 1,
  "rows": [
    {
      "instrument_kind": "option",
      "symbol": "cu2607C78000",
      "instrument_name": "沪铜C78000",
      "underlying_symbol": "cu2607",
      "exchange": "SHFE",
      "product_id": "cu",
      "expire_date": "20260624",
      "multiplier": 5,
      "option_type": "C",
      "strike_price": 78000.0,
      "strike_price_scaled": 780000000,
      "bid_price": 1260.0,
      "ask_price": 1280.0,
      "last_price": 1270.0,
      "open_price": 1240.0,
      "highest_price": 1295.0,
      "lowest_price": 1235.0,
      "bid_volume1": 12,
      "ask_volume1": 8,
      "volume": 1024,
      "open_interest": 55321,
      "pre_settlement_price": 1250.0,
      "update_time": "2026-06-03 09:31:15.500",
      "timestamp_ms": 1780000000000,
      "trading_day": "20260603",
      "action_day": "20260603"
    }
  ],
  "server_time_ms": 1780000000000
}

关键字段：

found：是否命中
query_type：查询类型，取值为 by_underlying、by_expire、by_symbol
contract_count：本次返回结果中的合约数量字段，仅用于业务结果展示，不参与平台计费
rows：结果行数组
server_time_ms：服务端返回时间

标的行还会返回当前交易日的 open_price、highest_price、lowest_price；三者来自行情源原始快照，不是服务端按查询窗口计算。尚未形成有效价格时可能为空。

5. Agent 接入规范

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

5.1 工具名建议

orange_resolve_subject
orange_basic_data

orange_resolve_subject 用于把中文品种名、代码前缀或完整合约解析为标准查询三元组。输入 query，可选 limit 默认 5、最大 5；输出 selected 和紧凑候选，不返回完整目录或行情。

5.2 输入结构建议

{
  "action": "by_underlying | by_expire | by_symbol",
  "params": {
    "underlying": "cu2607",
    "expire": "20260624",
    "symbol": "cu2607C78000"
  }
}

参数要求：

action = by_underlying：必须传 underlying
action = by_expire：必须传 underlying 和 expire
action = by_symbol：必须传 symbol

5.3 路由映射

by_underlying -> GET /api/v1/basic-data/query/by-underlying
by_expire -> GET /api/v1/basic-data/query/by-expire
by_symbol -> GET /api/v1/basic-data/query/by-symbol

5.4 Agent 调用流程建议

从安全存储读取 X-API-Token
用户只给出中文品种名、代码前缀或不完整合约时，先调用 orange_resolve_subject
found=true 且 ambiguous=false 时使用 selected 中的标准字段；否则向用户澄清
根据查询目标调用 orange_basic_data
检查平台响应 code
如果需要汇总分析，再基于 rows 做二次处理

Raw MCP 不公开完整目录 action；REST 的 /catalog 接口保持不变，供原有 HTTP 客户端继续使用。

5.5 Agent 错误处理建议

平台 code != 0：直接抛出平台错误
401/403：扣费侧使用 Authorization: Bearer <X-API-Token> 调用计费接口时鉴权失败
扣费失败：直接透传平台错误，提示用户检查 token 或计费服务状态
404 且 found = false：按“未命中”处理，不要当系统故障
上游超时或异常：建议重试，并保留原始错误信息

6. 计费与明细说明

平台在业务数据成功返回后，使用 OpenAI 兼容 POST /chat/completions 发起同步扣费
catalog 不触发扣费
query/by-underlying、query/by-expire、query/by-symbol 成功返回后触发扣费
对外业务接口协议保持不变，仍然由调用方传 X-API-Token
model 固定为 BasicData，用于标识业务类型
messages 保持最简，只携带本次请求路径和参数
扣费请求头格式固定为 Authorization: Bearer <X-API-Token>
外部计费接口返回 HTTP 200 视为扣费成功
扣费失败时，业务响应直接返回错误，不再写本地 usage 明细或异步扣费任务

7. 最小测试示例

查询单个期权：

curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-symbol?symbol=cu2607C78000' \
  -H 'X-API-Token: your_token_value'

查询某个标的某个到期日：

curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-expire?underlying=cu2607&expire=20260624' \
  -H 'X-API-Token: your_token_value'

8. 接入建议

手动接入适合后端服务、脚本、联调测试
Agent 接入适合自动查询、批量整理、策略辅助
建议给不同用途创建不同 Token，方便审计和隔离