行情历史服务
========================

用途
----

提供期货合约历史 K 线数据查询接口,返回 CSV 流式数据,便于用浏览器,脚本或数据分析工具快速拉取并直接消费(例如 ``requests`` / ``pandas.read_csv``).

权限与数据范围
^^^^^^^^^^^^^^

- 免费访问:无需 token,可获取 :strong:`最近 1 年` 的分钟线数据(``period=60``),以及 :strong:`任意历史区间` 的日线数据(``period=86400``).
- 专业版访问:在调用接口前访问 :doc:`token 服务 <token_server>` 获取 token,即可获取全部历史分钟线与日线数据.
  如需购买专业版访问权限,请前往 ``https://www.shinnytech.com/`` 用户中心购买.

历史数据范围(预计):提供 2021-01-01(含)以来的期货历史数据,支持 1 分钟线(``period=60``)与日线(``period=86400``).具体可用起始时间以合约实际上市/数据可得为准.

典型使用场景
^^^^^^^^^^^^

- 策略快速验证:免鉴权拉取近 1 年分钟线 + 任意区间日线,用于快速验证想法,参数敏感性分析与初步回测.
- 交易复盘与对账:按合约与时间区间导出 K 线(含成交量/持仓列),用于与成交记录,行情截图或其他数据源交叉核对.
- 数据分析/可视化:用脚本按需下载区间数据并落盘(CSV),便于后续清洗,特征工程,绘图与建模.
- 大模型/智能体应用:让大模型直接调用接口拉取历史数据,并生成对应的 Python 回测/分析脚本(建议在提示词中明确:合约,周期,起止时间,所需列 ``col``).

基础信息
--------

- 协议:HTTPS
- 返回类型:text/csv(流式)
- 时间字符串时区:``Asia/Shanghai``
- 服务地址:``https://edb.shinnytech.com/md``

接口:GET /kline
----------------

查询指定合约在给定时间范围内的 K 线数据.

请求参数(Query)
^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 12 6 62 20

   * - 参数名
     - 必填
     - 说明
     - 示例
   * - period
     - 是
     - 周期(秒),允许 ``60`` 或 ``86400``;其中 ``86400`` 表示按交易日返回日线(非自然日 24h)
     - 60
   * - symbol
     - 是
     - 合约标识
     - SHFE.rb2401
   * - start_time
     - 否
     - 起始时间 ``YYYY-MM-DD HH:MM:SS``;历史范围预计覆盖 2021-01-01(含)以来
     - 2023-08-01 09:00:00
   * - end_time
     - 否
     - 结束时间 ``YYYY-MM-DD HH:MM:SS``
     - 2023-08-01 15:00:00
   * - col
     - 否
     - 返回列,逗号分隔;可选 ``open,high,low,close,volume,open_oi,close_oi``
     - open,close,volume
   * - token
     - 否
     - 访问令牌(JWT),用于鉴权
     - eyJ...

合约标识(symbol)示例
^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 22 78

   * - symbol
     - 说明
   * - SHFE.cu1901
     - 上期所 cu1901 期货合约
   * - DCE.m1901
     - 大商所 m1901 期货合约
   * - CZCE.SR901
     - 郑商所 SR901 期货合约
   * - CFFEX.IF1901
     - 中金所 IF1901 期货合约
   * - INE.sc2109
     - 上期能源 sc2109 期货合约
   * - GFEX.si2301
     - 广期所 si2301 期货合约
   * - KQ.m@CFFEX.IF
     - 中金所 IF 品种主连合约(KQ 主连)
   * - KQ.i@SHFE.bu
     - 上期所 bu 品种指数(KQ 指数)

鉴权方式
^^^^^^^^

以下任意一种方式传递 JWT:

- Query 参数:``token=...``
- Header:``Authorization: Bearer <token>``(也支持不带 ``Bearer`` 的纯 token)

返回格式
^^^^^^^^

CSV 流式返回,首行为列名.

- ``datetime_nano`` 为纳秒时间戳(Unix epoch, ns).
- 默认返回列为:

::

  datetime_nano,open,high,low,close,volume,open_oi,close_oi

返回字段说明(字段格式参考"请求参数(Query)"的表格样式):

.. list-table::
   :header-rows: 1
   :widths: 16 14 52 18

   * - 字段名
     - 类型
     - 说明
     - 示例
   * - datetime_nano
     - int
     - K 线起始时间(纳秒时间戳,Unix epoch, ns)
     - 1690851600000000000
   * - open
     - float
     - 开盘价
     - 38520
   * - high
     - float
     - 最高价
     - 38610
   * - low
     - float
     - 最低价
     - 38480
   * - close
     - float
     - 收盘价
     - 38590
   * - volume
     - int
     - 成交量(手)
     - 1234
   * - open_oi
     - int
     - 开盘持仓量
     - 456789
   * - close_oi
     - int
     - 收盘持仓量
     - 456999

说明:

- HTTP 返回为 CSV 文本,字段在传输层面都是字符串;"类型"列描述的是字段语义类型.价格类字段按 ``float`` 解析,数量/持仓类字段按 ``int`` 解析即可(即便输出看起来没有小数点,价格字段也可能在其他合约/时段出现小数).
- 可通过 ``col`` 指定返回列(逗号分隔),例如仅返回 ``open,close,volume``.
- ``datetime_nano`` 始终作为第一列返回;其余列的顺序与 ``col`` 指定顺序一致(未指定 ``col`` 时使用默认列顺序).

错误返回
^^^^^^^^

错误以纯文本返回(非 JSON),包含错误码与提示,例如:

- ``400,invalid period``
- ``400,invalid time format``
- ``400,start_time after end_time``
- ``403,免费用户仅可以访问日线数据和近一年的分钟线数据, 请前往https://www.shinnytech.com/ 用户中心购买专业版或者企业版权限``

调用示例
--------

Python:

无需 token 直接请求数据:

.. code-block:: python

  import requests

  resp = requests.get(
      "https://edb.shinnytech.com/md/kline",
      params={
          "period": 86400,
          "symbol": "SHFE.rb2401",
          "start_time": "2023-08-01 09:00:00",
          "end_time": "2023-08-01 15:00:00",
      },
      timeout=30,
  )
  resp.raise_for_status()
  print(resp.text.splitlines()[:5])

获取 token 并请求数据:

.. code-block:: python

  import requests

  token_resp = requests.post(
      "https://edb.shinnytech.com/token",
      json={"username": "shinny_user", "password": "pw123"},
      timeout=5,
  )
  token_resp.raise_for_status()
  token = token_resp.json()["token"]

  resp = requests.get(
      "https://edb.shinnytech.com/md/kline",
      params={
          "period": 60,
          "symbol": "SHFE.rb2401",
          "start_time": "2023-08-01 09:00:00",
          "end_time": "2023-08-01 15:00:00",
      },
      headers={"Authorization": f"Bearer {token}"},
      timeout=30,
  )
  resp.raise_for_status()
  print(resp.text.splitlines()[:5])