# HTTP API

> The market-data REST protocol connectors implement, generated from its OpenAPI specification.

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


<Callout>
  Generated from 

  [`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). Summaries and descriptions are quoted from the specification, which is written in Chinese.
</Callout>

Connectors implement this REST protocol; the chart's provider router calls it. Responses are wrapped in `{ data, requestId }`, errors in `{ error }`.

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

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

| Parameter             | In   | Type                | Required |
| --------------------- | ---- | ------------------- | -------- |
| <code>sourceId</code> | path | <code>string</code> | Yes      |

| Status               | Media type                    | Schema                     | Description |
| -------------------- | ----------------------------- | -------------------------- | ----------- |
| <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" />

Request body: <code>InstrumentSearchRequest</code>

| Status           | Media type                    | Schema                                | Description |
| ---------------- | ----------------------------- | ------------------------------------- | ----------- |
| <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" />

Request body: <code>BarRequest</code>

| Status           | Media type                    | Schema                     | Description                |
| ---------------- | ----------------------------- | -------------------------- | -------------------------- |
| <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 能力时可请求。

Request body: <code>TradingCalendarRequest</code>

| Status           | Media type                    | Schema                               | Description                           |
| ---------------- | ----------------------------- | ------------------------------------ | ------------------------------------- |
| <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" />

Request body: <code>TimeShareRequest</code>

| Status           | Media type                    | Schema                         | Description               |
| ---------------- | ----------------------------- | ------------------------------ | ------------------------- |
| <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 无关。

| Parameter             | In    | Type                | Required |
| --------------------- | ----- | ------------------- | -------- |
| <code>sourceId</code> | path  | <code>string</code> | Yes      |
| <code>symbol</code>   | query | <code>string</code> | Yes      |

| Status               | Media type                     | Schema                        | Description |
| -------------------- | ------------------------------ | ----------------------------- | ----------- |
| <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>    | 标准错误响应      |