# HTTP 接口

> 连接器实现的行情 REST 协议，由 OpenAPI 规范生成。

Source: https://kcq.nebutra.com/zh/docs/market-data/http-api


<Callout>
  生成自 

  [`docs/market-data/market-data-v1.openapi.yaml`](https://github.com/TsekaLuk/KLineChartQuant/blob/1aa5e22c61313a34d08878ad895e604e0d4a85e9/docs/market-data/market-data-v1.openapi.yaml)

   (OpenAPI 3.1.0).
</Callout>

连接器实现这套 REST 协议，图表的 Provider 路由调用它。成功响应包在 `{ data, requestId }` 中，错误为 `{ error }`。

探测数据源可用性 [#探测数据源可用性]

<Endpoint method="GET" path="/api/v1/market-data/sources/{sourceId}/probe" />

| 参数                    | 位置   | 类型                  | 必填 |
| --------------------- | ---- | ------------------- | -- |
| <code>sourceId</code> | path | <code>string</code> | 是  |

| 状态码                  | 媒体类型                          | Schema                     | 说明      |
| -------------------- | ----------------------------- | -------------------------- | ------- |
| <code>200</code>     | <code>application/json</code> | <code>ProbeResponse</code> | 数据源探测结果 |
| <code>400</code>     | <code>application/json</code> | <code>ErrorEnvelope</code> | 标准错误响应  |
| <code>default</code> | <code>application/json</code> | <code>ErrorEnvelope</code> | 标准错误响应  |

搜索数据源内的标准品种目录 [#搜索数据源内的标准品种目录]

<Endpoint method="POST" path="/api/v1/market-data/instruments/search" />

请求体: <code>InstrumentSearchRequest</code>

| 状态码              | 媒体类型                          | Schema                                | 说明     |
| ---------------- | ----------------------------- | ------------------------------------- | ------ |
| <code>200</code> | <code>application/json</code> | <code>InstrumentSearchResponse</code> | 搜索结果   |
| <code>400</code> | <code>application/json</code> | <code>ErrorEnvelope</code>            | 标准错误响应 |
| <code>502</code> | <code>application/json</code> | <code>ErrorEnvelope</code>            | 标准错误响应 |

拉取指定品种、周期和 UTC 区间的 K 线 [#拉取指定品种周期和-utc-区间的-k-线]

<Endpoint method="POST" path="/api/v1/market-data/bars" />

请求体: <code>BarRequest</code>

| 状态码              | 媒体类型                          | Schema                     | 说明                         |
| ---------------- | ----------------------------- | -------------------------- | -------------------------- |
| <code>200</code> | <code>application/json</code> | <code>BarResponse</code>   | K 线序列；无行情时 data.items 为空数组 |
| <code>400</code> | <code>application/json</code> | <code>ErrorEnvelope</code> | 标准错误响应                     |
| <code>404</code> | <code>application/json</code> | <code>ErrorEnvelope</code> | 标准错误响应                     |
| <code>422</code> | <code>application/json</code> | <code>ErrorEnvelope</code> | 标准错误响应                     |
| <code>502</code> | <code>application/json</code> | <code>ErrorEnvelope</code> | 标准错误响应                     |

获取末根 K 线之后的交易槽位时间戳 [#获取末根-k-线之后的交易槽位时间戳]

<Endpoint method="POST" path="/api/v1/market-data/trading-calendar" />

仅当数据源及品种都声明 tradingCalendar 能力时可请求。

请求体: <code>TradingCalendarRequest</code>

| 状态码              | 媒体类型                          | Schema                               | 说明                                    |
| ---------------- | ----------------------------- | ------------------------------------ | ------------------------------------- |
| <code>200</code> | <code>application/json</code> | <code>TradingCalendarResponse</code> | 从 anchor 后第一槽开始的连续时间戳；可返回不足 count 的前缀 |
| <code>400</code> | <code>application/json</code> | <code>ErrorEnvelope</code>           | 标准错误响应                                |

拉取指定品种在单个交易日内的分时序列 [#拉取指定品种在单个交易日内的分时序列]

<Endpoint method="POST" path="/api/v1/market-data/timeshare" />

请求体: <code>TimeShareRequest</code>

| 状态码              | 媒体类型                          | Schema                         | 说明                        |
| ---------------- | ----------------------------- | ------------------------------ | ------------------------- |
| <code>200</code> | <code>application/json</code> | <code>TimeShareResponse</code> | 分时序列；无行情时 data.items 为空数组 |
| <code>400</code> | <code>application/json</code> | <code>ErrorEnvelope</code>     | 标准错误响应                    |
| <code>404</code> | <code>application/json</code> | <code>ErrorEnvelope</code>     | 标准错误响应                    |
| <code>422</code> | <code>application/json</code> | <code>ErrorEnvelope</code>     | 标准错误响应                    |
| <code>502</code> | <code>application/json</code> | <code>ErrorEnvelope</code>     | 标准错误响应                    |

订阅指定品种的实时逐笔 tick（SSE） [#订阅指定品种的实时逐笔-ticksse]

<Endpoint method="GET" path="/api/v1/market-data/sources/{sourceId}/ticks/stream" />

以 Server-Sent Events 持续推送逐笔 tick，事件 data 为 MarketTicksEvent JSON。 事件 id 为流内单调递增序号，断线重连时可经 Last-Event-ID 请求补帧； 新订阅只推送建立之后的 tick，不回放历史。tick 与 period 无关。

| 参数                    | 位置    | 类型                  | 必填 |
| --------------------- | ----- | ------------------- | -- |
| <code>sourceId</code> | path  | <code>string</code> | 是  |
| <code>symbol</code>   | query | <code>string</code> | 是  |

| 状态码                  | 媒体类型                           | Schema                        | 说明       |
| -------------------- | ------------------------------ | ----------------------------- | -------- |
| <code>200</code>     | <code>text/event-stream</code> | <code>MarketTicksEvent</code> | tick 事件流 |
| <code>400</code>     | <code>application/json</code>  | <code>ErrorEnvelope</code>    | 标准错误响应   |
| <code>default</code> | <code>application/json</code>  | <code>ErrorEnvelope</code>    | 标准错误响应   |