### Call Example for get_a_share_special_data_hot_stock_list_history

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_special_data_hot_stock_list_history

Example of the input parameters required to invoke the tool.

```text
工具：get_a_share_special_data_hot_stock_list_history  

参数：  

  - date: "2026-06-21"  
```

--------------------------------

### Call Example for get_a_share_index_prices_historical

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_index_prices_historical

Example of the input parameters required to invoke the tool.

```text
工具：get_a_share_index_prices_historical  

参数：  

  - thscode: "000001.SH"  

  - interval: "1d"  

  - start: 1716105600000  

  - end: 1747641600000
```

--------------------------------

### Tool Call Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_financials_cash_flow_statements

Example of the parameters required to invoke the get_a_share_financials_cash_flow_statements tool.

```text
工具：get_a_share_financials_cash_flow_statements  

参数：  

  - thscode: "600519.SH"  

  - period: "annual"  

  - start: 1577808000000  

  - end: 1735574400000
```

--------------------------------

### Tool Call Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_special_data_hot_stock_rank_trend

Example of the parameters required to invoke the get_a_share_special_data_hot_stock_rank_trend tool.

```text
工具：get_a_share_special_data_hot_stock_rank_trend  

参数：  

  - thscode: "300034.SZ"  

  - start_date: "2026-06-21"  

  - end_date: "2026-07-01"
```

--------------------------------

### Call Example for get_a_share_financials_indicators

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_financials_indicators

Example usage of the tool with specific thscode and report parameters.

```text
工具：get_a_share_financials_indicators  

参数：  

  - thscode: "300033.SZ"  

  - report: "2025-1"  
```

--------------------------------

### Tool Call Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_corporate_actions_adjustment_factors

Example of the parameters required to invoke the get_a_share_corporate_actions_adjustment_factors tool.

```text
工具：get_a_share_corporate_actions_adjustment_factors  

参数：  

  - thscode: "600519.SH"  

  - from: "2020-01-01"  

  - to: "2026-01-01"
```

--------------------------------

### Tool Invocation Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_index_catalog_ths_index_list

Example of how to call the get_a_share_index_catalog_ths_index_list tool with the cn_concept tag.

```text
工具：get_a_share_index_catalog_ths_index_list  

参数：  

  - tag: "cn_concept"
```

--------------------------------

### get_meta_tickers_list Tool Call Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_meta_tickers_list

Example of the parameters required to invoke the get_meta_tickers_list tool.

```text
工具：get_meta_tickers_list  

参数：  

  - asset_type: "a-share"  

  - limit: 1000  

  - offset: 0  
```

--------------------------------

### Request Balance Sheet Example

Source: https://fuyao.aicubes.cn/docs/api-reference/financials

Example request for Wuliangye's recent 4 quarterly reports.

```bash
# 五粮液最近 4 期季报（默认 limit=4）  

curl 'https://fuyao.aicubes.cn/api/a-share/financials/balance-sheets?thscode=000858.SZ&period=quarterly' \

  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### 查询财务指标数据

Source: https://fuyao.aicubes.cn/docs/api-reference/financial-indicators

使用 cURL 发送 GET 请求获取指定标的和报告期的财务指标。需在请求头中包含有效的 X-api-key。

```bash
curl 'https://fuyao.aicubes.cn/api/a-share/financials/indicators?thscode=300033.SZ&report=2025-1' \

  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### Request Cash Flow Statement Example

Source: https://fuyao.aicubes.cn/docs/api-reference/financials

Example request for Moutai's annual reports between 2020 and 2024 using a time range.

```bash
# 茅台 2020–2024 全部年报（时间区间模式）  

# start = 2020-01-01 00:00:00+08:00 → 1577808000000  

# end   = 2024-12-31 00:00:00+08:00 → 1735574400000  

curl 'https://fuyao.aicubes.cn/api/a-share/financials/cash-flow-statements?thscode=600519.SH&period=annual&start=1577808000000&end=1735574400000' \

  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### GET /api/a-share-index/prices/snapshot

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_index_prices_snapshot

按 thscodes 批量获取指数最新行情，覆盖上证交易所指数、深证交易所指数、同花顺板块与同花顺行业指数。

```APIDOC
## GET /api/a-share-index/prices/snapshot

### Description
按 thscodes 批量获取指数最新行情，覆盖上证交易所指数、深证交易所指数、同花顺板块与同花顺行业指数。本工具必须显式传入 thscodes，不支持空参数枚举全指数。

### Method
GET

### Endpoint
/api/a-share-index/prices/snapshot

### Parameters
#### Query Parameters
- **thscodes** (string) - Required - 逗号分隔的指数 thscode 列表，如 000001.SH,399001.SZ,886042.TI,881101.TI。
- **limit** (integer) - Optional - 与 A 股行情快照签名对齐，对本工具无效。
- **offset** (integer) - Optional - 与 A 股行情快照签名对齐，对本工具无效。

### Response
#### Success Response (200)
- **timestamp** (string) - 时间戳
- **total** (integer) - 返回记录总数
- **item** (array) - 指数行情数据列表

#### Response Example
{
  "timestamp": null,
  "total": 4,
  "item": [
    {
      "thscode": "000001.SH",
      "ticker": "000001",
      "last_price": 3388.06,
      "price_change": 12.21,
      "price_change_ratio_pct": 0.3617,
      "open_price": 3370.25,
      "high_price": 3392.18,
      "low_price": 3365.4,
      "prev_price": 3375.85,
      "volume": 321000000,
      "turnover": 420000000000
    }
  ]
}
```

--------------------------------

### GET /dump/market-dumps/adjustment-factors/download-url

Source: https://fuyao.aicubes.cn/docs/api-reference/market-dumps

获取全市场复权因子数据的 S3 预签名下载链接。

```APIDOC
## GET /dump/market-dumps/adjustment-factors/download-url

### Description
获取全 A 股全部历史的复权因子事件（分红 / 送股 / 配股）的 S3 预签名下载链接。

### Method
GET

### Endpoint
/dump/market-dumps/adjustment-factors/download-url
```

--------------------------------

### 标的检索 API 请求示例

Source: https://fuyao.aicubes.cn/docs/api-reference/ticker-search

使用 cURL 发送 GET 请求进行标的搜索。需在请求头中包含有效的 X-api-key。

```bash
# 按名称模糊搜索  
curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=%E5%B9%B3%E5%AE%89&limit=20' \
  -H 'X-api-key: <your-api-key>'
```

```bash
# 按 thscode 精确解析  
curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=600519.SH' \
  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### Call the get_a_share_special_data_skyrocket_list tool

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_special_data_skyrocket_list

Example usage of the tool specifying the hourly period parameter.

```text

工具：get_a_share_special_data_skyrocket_list  

参数：  

  - period: "hour"  



```

--------------------------------

### Call get_a_share_index_constituents_ths_stock_list

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_index_constituents_ths_stock_list

Example usage of the tool with a specific index THS code.

```text
工具：get_a_share_index_constituents_ths_stock_list  

参数：  

  - thscode: "886042.TI"
```

--------------------------------

### Response Format for get_a_share_special_data_hot_stock_list_history

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_special_data_hot_stock_list_history

Example of the JSON response structure returned by the tool.

```json
{

  "date": "2026-06-21",

  "date_ms": 1781971200000,

  "item": [

    {

      "thscode": "000725.SZ",

      "ticker": "000725",

      "name": "京东方A",

      "rank": 1

    }

  ]

}
```

--------------------------------

### Response Format for get_a_share_index_prices_historical

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_index_prices_historical

Example of the JSON response structure returned by the tool.

```json
{

  "timestamp": 1747584000000,

  "adjust": null,

  "item": [

    {

      "date_ms": 1716134400000,

      "open_price": 3108.22,

      "high_price": 3125.74,

      "low_price": 3101.15,

      "close_price": 3120.68,

      "volume": 281000000,

      "turnover": 360000000000

    }

  ]

}
```

--------------------------------

### GET /dump/market-dumps/daily-k-10d/download-url

Source: https://fuyao.aicubes.cn/docs/api-reference/market-dumps

获取最近 10 个交易日日 K 数据的 S3 预签名下载链接。

```APIDOC
## GET /dump/market-dumps/daily-k-10d/download-url

### Description
获取全 A 股最近 10 个交易日的日 K 行情（未复权）的 S3 预签名下载链接，适合高频增量同步。

### Method
GET

### Endpoint
/dump/market-dumps/daily-k-10d/download-url
```

--------------------------------

### GET /api/meta/tickers/list

Source: https://fuyao.aicubes.cn/docs/api-reference/ticker-list

批量获取标的列表，支持按资产类别过滤，并使用 offset/limit 进行分页。

```APIDOC
## GET /api/meta/tickers/list

### Description
批量获取代码表，支持按资产类别过滤。采用 offset / limit 分页，调用方循环递增 offset 直到 item.length < limit 即可取尽。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/meta/tickers/list

### Parameters
#### Query Parameters
- **asset_type** (string) - Optional - 资产类别：a-share / a-share-index。默认值: a-share
- **limit** (integer) - Optional - 单页条数，最大 10000。默认值: 1000
- **offset** (integer) - Optional - 分页偏移。默认值: 0

### Request Example
curl 'https://fuyao.aicubes.cn/api/meta/tickers/list?asset_type=a-share&limit=1000&offset=0' \
  -H 'X-api-key: <your-api-key>'

### Response
#### Success Response (200)
- **code** (integer) - 状态码
- **message** (string) - 响应信息
- **request_id** (string) - 请求唯一标识
- **data** (object) - 包含 timestamp 和 item 列表的数据对象

#### Response Example
{
  "code": 0,
  "message": "success",
  "request_id": "f7g8h9i0",
  "data": {
    "timestamp": 1716105600000,
    "item": [
      {
        "thscode": "600519.SH",
        "ticker": "600519",
        "name": "贵州茅台",
        "exchange": "SH",
        "asset_type": "a-share",
        "currency": "CNY"
      }
    ]
  }
}
```

--------------------------------

### GET /dump/market-dumps/daily-k/download-url

Source: https://fuyao.aicubes.cn/docs/api-reference/market-dumps

获取 10 年全量日 K 数据的 S3 预签名下载链接。

```APIDOC
## GET /dump/market-dumps/daily-k/download-url

### Description
获取全 A 股最近约 10 年的日 K 行情（未复权）的 S3 预签名下载链接。

### Method
GET

### Endpoint
/dump/market-dumps/daily-k/download-url
```

--------------------------------

### 获取个股排名走势 API 端点

Source: https://fuyao.aicubes.cn/docs/api-reference/hot-list-data

用于查询个股热榜排名走势的 HTTP GET 请求路径。

```http
GET /api/a-share/special-data/hot-stock-rank-trend
```

--------------------------------

### GET /api/a-share/prices/snapshot

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_prices_snapshot

获取 A 股行情快照。当提供 thscodes 时按顺序批量获取；省略时则根据 limit 和 offset 分页遍历全市场代码。

```APIDOC
## GET /api/a-share/prices/snapshot

### Description
获取 A 股行情快照。`thscodes` 显式给定时按入参顺序批量取数；省略时遍历完整 A 股代码表并按 `limit`/`offset` 分页。返回每只标的的最新价、涨跌额、涨跌幅、开盘/最高/最低/前收价、成交量、成交额。

### Method
GET

### Endpoint
/api/a-share/prices/snapshot

### Parameters
#### Query Parameters
- **thscodes** (string) - Optional - 逗号分隔的 thscode 列表，如 `600519.SH,000001.SZ`。给定时忽略 `limit` / `offset`。
- **limit** (integer) - Optional - 分页大小，默认 100，仅在 `thscodes` 省略时生效。
- **offset** (integer) - Optional - 分页偏移，默认 0，仅在 `thscodes` 省略时生效。

### Request Example
GET /api/a-share/prices/snapshot?thscodes=600519.SH,000001.SZ

### Response
#### Success Response (200)
- **timestamp** (string) - 数据时间戳
- **total** (integer) - 总记录数
- **item** (array) - 行情快照列表

#### Response Example
{
  "timestamp": "2023-10-27T15:00:00Z",
  "total": 2,
  "item": [
    {
      "thscode": "600519.SH",
      "ticker": "600519",
      "last_price": 1277.8,
      "price_change": 21.8,
      "price_change_ratio_pct": 1.735669,
      "open_price": 1252.08,
      "high_price": 1282,
      "low_price": 1250.21,
      "prev_price": 1256,
      "volume": 3098875,
      "turnover": 3937375200
    }
  ]
}
```

--------------------------------

### Balance Sheet Response Example

Source: https://fuyao.aicubes.cn/docs/api-reference/financials

JSON response structure for balance sheet data.

```json
{

  "code": 0,

  "message": "success",

  "request_id": "f6g7h8i9",

  "data": {

    "timestamp": 1735574400000,

    "item": [

      {

        "thscode": "000858.SZ",

        "ticker": "000858",

        "period": "quarterly",

        "fiscal_year": 2024,

        "fiscal_period": "Q4",

        "report_date_ms": 1735574400000,

        "period_end_ms": 1735574400000,

        "currency": "CNY",

        "assets_total": 250000000000,

        "total_current_assets": 200000000000,

        "non_current_nets_total": 50000000000,

        "cash": 130000000000,

        "accounts_receivable": 500000000,

        "total_debt": 60000000000,

        "holder_equity_total": 190000000000

      }

    ]

  }

}
```

--------------------------------

### Market Snapshot Response Structure

Source: https://fuyao.aicubes.cn/docs/api-reference/prices

Example of the standardized JSON response for a market snapshot request.

```json
{
  "code": 0,
  "message": "success",
  "request_id": "7e25804be878464ba420037155f041e6",
  "data": {
    "timestamp": null,
    "total": 2,
    "item": [
      {
        "thscode": "600519.SH",
        "ticker": "600519",
        "volume": 3098875,
        "turnover": 3937375200,
        "last_price": 1277.8,
        "price_change": 21.8,
        "price_change_ratio_pct": 1.735669,
        "open_price": 1252.08,
        "high_price": 1282,
        "low_price": 1250.21,
        "prev_price": 1256
      }
    ]
  }
}
```

--------------------------------

### Call get_a_share_financials_balance_sheets with parameters

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_financials_balance_sheets

Example of invoking the tool with a specific stock ticker and quarterly reporting period.

```text
工具：get_a_share_financials_balance_sheets  

参数：  

  - thscode: "000858.SZ"  

  - period: "quarterly"
```

--------------------------------

### cURL Request for Limit-Up Ladder

Source: https://fuyao.aicubes.cn/docs/api-reference/limit-up-data

Example request using cURL. Ensure the X-api-key header is set with your valid API key.

```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/limit-up-ladder' \
  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### GET /api/a-share/special-data/dragon-tiger-list

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_special_data_dragon_tiger_list

查询指定日期和类型的龙虎榜榜单数据。

```APIDOC
## GET /api/a-share/special-data/dragon-tiger-list

### Description
查询龙虎榜榜单。支持按榜单类型和交易日期进行筛选。

### Method
GET

### Endpoint
/api/a-share/special-data/dragon-tiger-list

### Parameters
#### Query Parameters
- **board_type** (string) - Optional - 榜单类型：all (全部), org (机构榜), hot_money (游资榜)。默认值为 all。
- **date** (string) - Optional - 目标交易日，格式 YYYY-MM-DD。缺省由服务端取最新可用日期。

### Response
#### Success Response (200)
- **timestamp** (number) - 时间戳
- **board_type** (string) - 榜单类型
- **trade_date** (string) - 交易日期
- **count** (number) - 总数
- **stock_count** (number) - 股票总数
- **stock_items** (array) - 股票列表
- **hot_money_items** (array) - 游资列表

#### Response Example
{
  "timestamp": 1782921600000,
  "board_type": "all",
  "trade_date": "2026-07-01",
  "count": 80,
  "stock_count": 75,
  "stock_items": [
    {
      "thscode": "002407.SZ",
      "ticker": "002407",
      "name": "多氟多",
      "net_value": 1786253128.23,
      "hot_rank": 2,
      "range_days": 3
    }
  ],
  "hot_money_items": []
}
```

--------------------------------

### GET /api/a-share/special-data/dragon-tiger-list

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

按交易日返回全部、机构榜或游资榜。

```APIDOC
## GET /api/a-share/special-data/dragon-tiger-list

### Description
按交易日返回全部、机构榜或游资榜。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/dragon-tiger-list
```

--------------------------------

### Response Format Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_special_data_hot_stock_rank_trend

The JSON structure returned by the tool, containing a timestamp and a list of ranking trend items.

```json
{

  "timestamp": 1781971200000,

  "item": [

    {

      "thscode": "300034.SZ",

      "ticker": "300034",

      "date": "2026-06-21",

      "date_ms": 1781971200000,

      "rank": 1740

    }

  ]

}
```

--------------------------------

### GET /api/a-share/special-data/anomaly-analysis-stock

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

按同花顺代码批量查询当日个股异动原因。

```APIDOC
## GET /api/a-share/special-data/anomaly-analysis-stock

### Description
按同花顺代码批量查询当日个股异动原因。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/anomaly-analysis-stock
```

--------------------------------

### GET /api/a-share/special-data/anomaly-analysis-list

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

查询当日个股异动原因，可选按异动标签过滤。

```APIDOC
## GET /api/a-share/special-data/anomaly-analysis-list

### Description
查询当日个股异动原因，可选按异动标签过滤。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/anomaly-analysis-list
```

--------------------------------

### Response Format Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_corporate_actions_adjustment_factors

JSON structure returned by the tool, containing the stock identifier and a list of adjustment factor items sorted by ex-date.

```json
{

  "thscode": "600519.SH",

  "ticker": "600519",

  "item": [

    {

      "ticker": "600519",

      "ex_date_ms": 1766073600000,

      "dividend_per_share": 23.957,

      "per_share_bonus": 0

    },

    {

      "ticker": "600519",

      "ex_date_ms": 1437062400000,

      "dividend_per_share": 4.374,

      "per_share_bonus": 0.1

    }

  ]

}
```

--------------------------------

### GET /api/a-share/special-data/hot-stock-list-history

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

按自然日返回历史热股榜排行。

```APIDOC
## GET /api/a-share/special-data/hot-stock-list-history

### Description
按自然日返回历史热股榜排行。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/hot-stock-list-history
```

--------------------------------

### 调用飙升榜 API (cURL)

Source: https://fuyao.aicubes.cn/docs/api-reference/hot-list-data

通过 cURL 发起小时榜查询请求，需在请求头中提供有效的 X-api-key。

```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/skyrocket-list?period=hour' \
  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### GET /api/a-share/special-data/dragon-tiger-list

Source: https://fuyao.aicubes.cn/docs/api-reference/dragon-tiger-data

按交易日返回龙虎榜首页整体榜单。支持查询全部、机构榜或游资榜数据。

```APIDOC
## GET /api/a-share/special-data/dragon-tiger-list

### Description
按交易日返回龙虎榜首页整体榜单。省略 date 时，若今天是交易日则默认取上一个交易日；若今天不是交易日，则默认取今天之前最近一个交易日。显式传入非交易日会返回参数错误。

### Method
GET

### Endpoint
/api/a-share/special-data/dragon-tiger-list

### Parameters
#### Query Parameters
- **board_type** (enum) - Optional - 榜单类型：all (全部) / org (机构榜) / hot_money (游资榜)。默认值: all
- **date** (string) - Optional - 目标交易日，格式 yyyy-MM-dd；只支持一年内数据。

### Request Example
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/dragon-tiger-list?board_type=org&date=2026-07-01' \
  -H 'X-api-key: <your-api-key>'

### Response
#### Success Response (200)
- **code** (integer) - 业务状态码
- **message** (string) - 响应消息
- **data** (object) - 龙虎榜榜单容器

#### Response Example
{
  "code": 0,
  "message": "success",
  "data": {
    "trade_date": "2026-07-01",
    "stock_items": [
      {
        "thscode": "002407.SZ",
        "name": "多氟多",
        "net_value": 1786253128.23
      }
    ]
  }
}
```

--------------------------------

### GET /api/a-share/financials/indicators

Source: https://fuyao.aicubes.cn/docs/api-reference/financial-indicators

获取指定 A 股标的在特定报告期的财务指标数据。

```APIDOC
## GET /api/a-share/financials/indicators

### Description
获取单只 A 股在指定报告期下的五类指标数据（成长、盈利、偿债、营运、现金流）。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/financials/indicators

### Parameters
#### Query Parameters
- **thscode** (string) - Required - 单只标的 thscode，含交易所后缀，如 300033.SZ。
- **report** (string) - Required - 报告期，格式为 yyyy-1, yyyy-2, yyyy-3, yyyy-4。

### Request Example
curl 'https://fuyao.aicubes.cn/api/a-share/financials/indicators?thscode=300033.SZ&report=2025-1' \
  -H 'X-api-key: <your-api-key>'

### Response
#### Success Response (200)
- **code** (integer) - 业务状态码，0 表示成功。
- **message** (string) - 业务状态说明。
- **request_id** (string) - 请求追踪 ID。
- **data** (object) - 包含 thscode, report 及 abilities 数组的财务数据对象。

#### Response Example
{
  "code": 0,
  "message": "success",
  "request_id": "a1b2c3d4e5f6789012345678abcdef01",
  "data": {
    "thscode": "300033.SZ",
    "report": "2025-1",
    "abilities": [
      {
        "ability": "growth",
        "indicators": [
          {
            "index_id": "total_assets_growth_ratio",
            "value": "-16.0031"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### GET /api/a-share/special-data/hot-stock-rank-trend

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

查询单只 A 股一段时间内的热榜排名走势。

```APIDOC
## GET /api/a-share/special-data/hot-stock-rank-trend

### Description
查询单只 A 股一段时间内的热榜排名走势。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/hot-stock-rank-trend
```

--------------------------------

### Response Format Example

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_financials_cash_flow_statements

The JSON structure returned by the tool, containing a timestamp and a list of cash flow statement items.

```json
{

  "timestamp": 1735574400000,

  "item": [

    {

      "thscode": "600519.SH",

      "ticker": "600519",

      "period": "annual",

      "fiscal_year": 2024,

      "fiscal_period": "FY",

      "report_date_ms": 1735574400000,

      "period_end_ms": 1735574400000,

      "currency": "CNY",

      "act_cash_flow_net": 92000000000,

      "invest_cash_flow_net": -3000000000,

      "financing_cash_flow_net": -65000000000,

      "pay_fixed_assets_etc_cash": 3500000000,

      "pay_dividends_profits_interest_cash": 64000000000,

      "cash_equivalents_net_addition": 24000000000

    }

  ]

}
```

--------------------------------

### 设置本地调试 API Key

Source: https://fuyao.aicubes.cn/docs/mcp/overview

在本地调试或自托管环境下，通过环境变量注入 API Key 以进行鉴权。

```bash
export API_KEY="<your-api-key>"
```

--------------------------------

### Call get_a_share_financials_income_statements

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_financials_income_statements

Example of invoking the tool with a specific stock code, annual period, and a limit of 3 periods.

```text
工具：get_a_share_financials_income_statements  

参数：  

  - thscode: "600519.SH"  

  - period: "annual"  

  - limit: 3
```

--------------------------------

### GET /api/a-share-index/prices/historical

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_a_share_index_prices_historical

获取单只指数的历史 K 线数据，支持上证、深证及同花顺板块指数。

```APIDOC
## GET /api/a-share-index/prices/historical

### Description
获取单只指数的历史 K 线数据，覆盖上证交易所指数、深证交易所指数、同花顺板块与同花顺行业指数。每次只能传一个 thscode，只支持 start / end 时间区间模式，窗口最长 10 年。

### Method
GET

### Endpoint
/api/a-share-index/prices/historical

### Parameters
#### Query Parameters
- **thscode** (string) - Required - 单只指数 thscode，如 000001.SH / 399001.SZ / 886042.TI / 881101.TI。
- **interval** (string) - Required - K 线周期，当前仅支持 1d（日线）。
- **start** (long) - Required - 起始时间，毫秒 Unix 时间戳。
- **end** (long) - Required - 结束时间，毫秒 Unix 时间戳。

### Response
#### Success Response (200)
- **timestamp** (long) - 数据时间戳
- **adjust** (null) - 复权标识，固定为 null
- **item** (array) - 历史价格数据列表

#### Response Example
{
  "timestamp": 1747584000000,
  "adjust": null,
  "item": [
    {
      "date_ms": 1716134400000,
      "open_price": 3108.22,
      "high_price": 3125.74,
      "low_price": 3101.15,
      "close_price": 3120.68,
      "volume": 281000000,
      "turnover": 360000000000
    }
  ]
}
```

--------------------------------

### 完整 Python 脚本

Source: https://fuyao.aicubes.cn/docs/api-reference/market-dumps

用于解析和检查市场数据转储文件的完整 Python 实现，包含参数解析和数据处理逻辑。

```python
#!/usr/bin/env python3

"""
Read and inspect Fuyao market-dump Parquet files for all publishable kinds:

  - daily-k             rows keyed by (thscode, date_ms),     dump_id a_share_daily_k_1d_none_10y
  - daily-k-10d         rows keyed by (thscode, date_ms),     dump_id a_share_daily_k_1d_none_10d
  - adjustment-factors  rows keyed by (thscode, ex_date_ms),  dump_id a_share_adjustment_factors_event_none_all

The kind is auto-detected from the Parquet schema (presence of `ex_date_ms`),
so the same CLI works for either dump.

Examples (daily-k):
  python3 scripts/read_market_dump.py build/dump/a_share_daily_k_1d_none_10y/20260602/manifest.json
  python3 scripts/read_market_dump.py build/dump/a_share_daily_k_1d_none_10y/20260602 --ticker 600519.SH
  python3 scripts/read_market_dump.py build/dump/a_share_daily_k_1d_none_10d/20260602 --check-duplicates
  python3 scripts/read_market_dump.py build/dump/a_share_daily_k_1d_none_10d/20260602 --export-csv /tmp/sample.csv

Examples (adjustment-factors):
  python3 scripts/read_market_dump.py build/dump/a_share_adjustment_factors_event_none_all/20260602
  python3 scripts/read_market_dump.py build/dump/a_share_adjustment_factors_event_none_all/20260602 --ticker 600519.SH
  python3 scripts/read_market_dump.py build/dump/a_share_adjustment_factors_event_none_all/20260602 --check-duplicates

Inspecting a file downloaded via GET /dump/market-dumps/<kind>/download-url:
  python3 scripts/read_market_dump.py /tmp/market-dump-daily-k.parquet
"""

from __future__ import annotations

import argparse
import csv
import hashlib
import json
import sys
from collections import defaultdict
from dataclasses import dataclass
from datetime import date, datetime, time, timedelta
from pathlib import Path
from typing import Any
from zoneinfo import ZoneInfo


ZONE = ZoneInfo("Asia/Shanghai")
DEFAULT_COLUMNS = [
    "thscode",
    "currency",
    "interval",
    "adjusted",
    "date_ms",
    "open_price",
    "high_price",
    "low_price",
    "close_price",
    "volume",
    "turnover",
]
ADJUSTMENT_FACTOR_COLUMNS = [
    "thscode",
    "ticker",
    "ex_date_ms",
    "dividend_per_share",
    "per_share_bonus",
    "allotment_ratio",
    "allotment_price",
    "currency",
]


@dataclass(frozen=True)
class ResolvedInput:
    manifest_path: Path | None
    parquet_path: Path
    manifest: dict[str, Any] | None


def import_pyarrow():
    try:
        import pyarrow.parquet as pq  # type: ignore
    except ModuleNotFoundError:
        print(
            "ERROR: reading Parquet requires pyarrow.\n"
            "Install it with:\n"
            "  python3 -m pip install pyarrow\n",
            file=sys.stderr,
        )
        raise SystemExit(1)
    return pq


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Read and inspect Fuyao market dump Parquet files.",
        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
    )
    parser.add_argument(
        "path",
        help=(
            "Path to manifest.json, a version directory containing manifest.json, "
            "or a .parquet file."
        ),
    )
    parser.add_argument(
        "--prefer",
        choices=["current", "compact"],
        default="compact",
        help=(
            "When reading a manifest, prefer compact_file if present, otherwise "
            "use the manifest current file_name."
        ),
    )
    parser.add_argument("--ticker", action="append", help="Filter by thscode. Can be repeated.")
    parser.add_argument("--from-date", help="Filter date_ms from this YYYY-MM-DD date, inclusive.")
    parser.add_argument("--to-date", help="Filter date_ms to this YYYY-MM-DD date, inclusive.")
    parser.add_argument("--limit", type=int, default=20, help="Number of sample rows to print.")
    parser.add_argument("--batch-size", type=int, default=65536, help="Parquet streaming batch size.")
    parser.add_argument(
        "--check-duplicates",
```

--------------------------------

### GET /api/meta/tickers/search

Source: https://fuyao.aicubes.cn/docs/api-reference/ticker-search

按关键词（thscode / ticker / 中英文名称）跨市场消歧，支持子串匹配。

```APIDOC
## GET /api/meta/tickers/search

### Description
按关键词（thscode / ticker / 中英文名称）跨市场消歧，支持子串匹配。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/meta/tickers/search

### Parameters
#### Query Parameters
- **q** (string) - Required - 搜索关键词：完整 thscode、ticker 代码或中英文名称（支持子串匹配）。
- **asset_type** (string) - Optional - 资产类别过滤：`a-share`(A 股) / `a-share-index`(A 股指数)。
- **limit** (integer) - Optional - 返回上限，最大 50，默认 10。

### Request Example
curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=平安&limit=20' \
  -H 'X-api-key: <your-api-key>'

### Response
#### Success Response (200)
- **timestamp** (long) - 数据就绪时间（毫秒）。
- **item** (array) - 标的列表。

#### Response Example
{
  "code": 0,
  "message": "success",
  "request_id": "c3d4e5f6",
  "data": {
    "timestamp": 1716105600000,
    "item": [
      {
        "thscode": "601318.SH",
        "ticker": "601318",
        "name": "中国平安",
        "exchange": "SH",
        "asset_type": "a-share",
        "currency": "CNY"
      }
    ]
  }
}
```

--------------------------------

### Pagination Logic for get_meta_tickers_list

Source: https://fuyao.aicubes.cn/docs/mcp/tools/get_meta_tickers_list

Demonstrates how to iterate through pages using offset and limit until all items are retrieved.

```pseudocode
offset = 0  

loop:  

  resp = get_meta_tickers_list(offset=offset, limit=1000)  

  consume(resp.item)  

  if len(resp.item) < 1000: break  

  offset += 1000  
```

--------------------------------

### GET /api/a-share/corporate-actions/adjustment-factors

Source: https://fuyao.aicubes.cn/docs/api-reference/corporate-actions

获取单只标的的 A 股复权因子事件流。每次请求仅支持单个 thscode。

```APIDOC
## GET /api/a-share/corporate-actions/adjustment-factors

### Description
获取单只标的的 A 股复权因子事件流。每次请求仅支持单个 thscode。

### Method
GET

### Endpoint
/api/a-share/corporate-actions/adjustment-factors

### Parameters
#### Query Parameters
- **thscode** (string) - Required - 单只标的 thscode，不接受逗号。
- **from** (string) - Optional - 事件起始日，格式 YYYY-MM-DD。
- **to** (string) - Optional - 事件截止日，格式 YYYY-MM-DD。

### Request Example
curl 'https://fuyao.aicubes.cn/api/a-share/corporate-actions/adjustment-factors?thscode=600519.SH' \
  -H 'X-api-key: <your-api-key>'

### Response
#### Success Response (200)
- **code** (number) - 状态码，0 表示成功。
- **message** (string) - 响应消息。
- **data** (object) - 包含 thscode, ticker 和 item 列表的复权因子数据。

#### Response Example
{
  "code": 0,
  "message": "success",
  "request_id": "558c1d59d2e548149fb27b83eca5016a",
  "data": {
    "thscode": "600519.SH",
    "ticker": "600519",
    "item": [
      {
        "ticker": "600519",
        "ex_date_ms": 1766073600000,
        "dividend_per_share": 23.957,
        "per_share_bonus": 0
      }
    ]
  }
}
```

--------------------------------

### Index Price Snapshot Response Example

Source: https://fuyao.aicubes.cn/docs/api-reference/a-share-index

JSON structure returned when querying index price snapshots.

```json
{
  "code": 0,
  "message": "success",
  "request_id": "7e25804be878464ba420037155f041e6",
  "data": {
    "timestamp": null,
    "total": 4,
    "item": [
      {
        "thscode": "000001.SH",
        "ticker": "000001",
        "last_price": 3388.06,
        "price_change": 12.21,
        "price_change_ratio_pct": 0.3617,
        "open_price": 3370.25,
        "high_price": 3392.18,
        "low_price": 3365.4,
        "prev_price": 3375.85,
        "volume": 321000000,
        "turnover": 420000000000
      }
    ]
  }
}
```

--------------------------------

### GET /api/a-share/special-data/skyrocket-list

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

查询 A 股热度排名飙升榜 Top30，支持日榜与小时榜。

```APIDOC
## GET /api/a-share/special-data/skyrocket-list

### Description
查询 A 股热度排名飙升榜 Top30，支持日榜与小时榜。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/skyrocket-list
```

--------------------------------

### GET /api/a-share/special-data/limit-up-ladder

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

返回近 30 个交易日的连板梯队矩阵。

```APIDOC
## GET /api/a-share/special-data/limit-up-ladder

### Description
返回近 30 个交易日的连板梯队矩阵。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/limit-up-ladder
```

--------------------------------

### Fetch Index Lists via cURL

Source: https://fuyao.aicubes.cn/docs/api-reference/a-share-index

Examples for retrieving concept or industry index lists using cURL.

```bash
# 拉取全部概念板块  
curl 'https://fuyao.aicubes.cn/api/a-share-index/catalog/ths-index-list?tag=cn_concept' \
  -H 'X-api-key: <your-api-key>'

# 拉取全部同花顺行业指数  
curl 'https://fuyao.aicubes.cn/api/a-share-index/catalog/ths-index-list?tag=industry' \
  -H 'X-api-key: <your-api-key>'
```

--------------------------------

### 命令行使用示例

Source: https://fuyao.aicubes.cn/docs/api-reference/market-dumps

展示如何通过命令行参数读取 Parquet 文件、过滤特定代码、按日期范围导出以及检查数据唯一性。

```bash
# 下载到本地后直接读取

python3 read_market_dump.py /tmp/a_share_daily_k.parquet



# 过滤特定 thscode

python3 read_market_dump.py /tmp/a_share_daily_k.parquet --ticker 600519.SH



# 按日期范围导出 CSV

python3 read_market_dump.py /tmp/a_share_daily_k.parquet \

  --from-date 2025-01-01 --to-date 2025-12-31 \

  --export-csv /tmp/sample.csv



# 检查 (thscode, date_ms) 唯一性

python3 read_market_dump.py /tmp/a_share_daily_k.parquet --check-duplicates
```

--------------------------------

### GET /api/a-share/special-data/limit-up-pool

Source: https://fuyao.aicubes.cn/docs/api-reference/special-data

按交易日返回 A 股涨停 / 连板股票池。

```APIDOC
## GET /api/a-share/special-data/limit-up-pool

### Description
按交易日返回 A 股涨停 / 连板股票池。

### Method
GET

### Endpoint
https://fuyao.aicubes.cn/api/a-share/special-data/limit-up-pool
```