docs/API.md

# 股票数据 API 接口说明

## 通用规则

- Base URL：`https://你的-space.hf.space/api/v1`
- 鉴权：如果配置 `STOCK_DATA_API_KEY`，请求头使用 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`。
- 股票代码：支持 `600519`、`600519.SH`、`sh600519`、`000001.SZ`。
- 日期：支持 `YYYYMMDD` 或 `YYYY-MM-DD`。

所有成功响应都包含：

```json
{
  "ok": true,
  "data": {},
  "meta": {
    "endpoint": "stock_quote",
    "source": "akshare.stock_zh_a_spot_em",
    "cache": {
      "hit": false,
      "stale": false,
      "ttl_seconds": 300,
      "created_at": "2026-06-06T09:00:00+00:00",
      "expires_at": "2026-06-06T09:05:00+00:00",
      "row_count": 1
    },
    "attempts": []
  }
}
```

`cache.stale=true` 表示实时源全部失败，服务使用了过期缓存兜底。

## 个股

### 最新行情

```http
GET /stocks/600519/quote
```

来源顺序：

1. `sina.hq.realtime`
2. `akshare.stock_zh_a_spot_em`
3. `akshare.stock_zh_a_hist.latest`
4. `akshare.stock_zh_a_daily.sina.latest`
5. `yahoo.chart.quote`

### 日 K

```http
GET /stocks/600519/daily?days=60&adjust=qfq
GET /stocks/600519/daily?start_date=2025-01-01&end_date=2025-12-31&adjust=qfq
```

缓存策略：

- 明确历史区间且 `end_date` 早于今天：200 天。
- 默认滚动到今天：6 小时。

来源顺序：
1. `yahoo.chart.daily`
2. `eastmoney.push2his.stock_kline`
3. `akshare.stock_zh_a_hist.eastmoney`
4. `akshare.stock_zh_a_daily.sina`
5. `baostock.query_history_k_data_plus`

`yahoo.chart.daily` is now the first source for A-share daily K-line data and supports `start_date` / `end_date`; AKShare and BaoStock remain fallbacks.

### 技术指标

```http
GET /stocks/600519/technical?days=120
GET /stocks/600519/technical?days=120&history_days=20
```

当前返回 MA、EMA、RSI、KDJ、MACD、Bollinger、OBV、ATR、BIAS、CCI、VWAP。

### 筹码估算

```http
GET /stocks/600519/chip?lookback_days=60
```

这是基于价格和成交量的简化筹码估算，适合给短线技能做参考，不等同于交易软件里的逐笔筹码模型。

### 个股资金流

```http
GET /stocks/600519/fund-flow?days=10
```

来源轮换：

```text
1. scrapling.eastmoney.stock_fflow（Scrapling 网页抓取，主力）
2. akshare.stock_individual_fund_flow.eastmoney
3. eastmoney.push2his/push2/push2delay.stock_fflow
```

### 新闻与公告

```http
GET /stocks/600519/news?limit=30
GET /stocks/600519/notices?limit=30
```

## 市场与板块

### 涨跌停池

```http
GET /market/limit-up?date=20260605&limit=100
GET /market/limit-down?date=20260605&limit=100
```

`/market/limit-up` 会在东方财富涨停池不可用时切换到同花顺 `limit_up_pool` 直连接口，字段会保留同花顺返回的开板次数、封单量、涨停原因、连板天数等明细。

### 市场宽度与温度

```http
GET /market/breadth
GET /market/temperature
```

市场宽度来源顺序：

1. `akshare.stock_board_industry_summary_ths`
2. `akshare.stock_zh_a_spot_em`

市场温度会组合涨停池、跌停池和市场宽度。

### 股指期货基差

```http
GET /market/futures-basis?days=10
```

返回 IF/IH/IC/IM 四个合约的基差（现货指数 − 期货主力合约）。`days=1` 返回当日实时基差 + 日内 5 分钟走势（`intraday`），`days>1` 返回历史趋势含 `by_date` 分组。服务端并发拉取 Sina 现货指数和中金所主力连续数据，缓存 10 分钟。

### A 股交易日历

```http
GET /market/trade-calendar
GET /market/trade-calendar?start_date=2026-01-01&end_date=2026-12-31&limit=300
```

返回 Sina A 股交易日历，适合上层任务调度、回测日期过滤和补数窗口计算。

### 概念与行业资金

```http
GET /boards/concepts/flow?symbol=即时&limit=1000
GET /boards/industries/flow?symbol=即时&limit=1000
```

来源顺序：

- 概念：`eastmoney.push2delay.board_flow.concept` -> `eastmoney.push2.board_flow.concept` -> `stock_fund_flow_concept` -> `stock_board_concept_name_em`
- 行业：`eastmoney.push2delay.board_flow.industry` -> `eastmoney.push2.board_flow.industry` -> `stock_fund_flow_industry` -> `stock_board_industry_name_em`

## 财务与宏观

### 财务

```http
GET /stocks/600519/financial?kind=abstract
GET /stocks/600519/financial?kind=indicators&start_year=2023&end_year=2025
GET /stocks/600519/financial?kind=forecast&report_date=20260331
GET /stocks/600519/financial?kind=express&report_date=20260331
GET /stocks/688981/financial?kind=abstract&start_year=2023&end_year=2025&limit=50
GET /stocks/600519/income?kind=ytd&limit=10
GET /stocks/600519/income?kind=quarterly&limit=10
GET /stocks/600519/balancesheet?limit=10
GET /stocks/600519/cashflow?kind=ytd&limit=10
GET /stocks/600519/cashflow?kind=quarterly&limit=10
GET /stocks/600519/dividends?kind=main&limit=20
GET /stocks/600519/dividends?kind=allotment&limit=20
GET /stocks/600519/equity-history?limit=20
GET /stocks/600519/freeholders?limit=20
```

| 参数 | 默认 | 说明 |
|---|---:|---|
| `kind` | `abstract` | `abstract`、`indicators`、`forecast`、`express` |
| `limit` | `20` | 返回条数，范围 1-200 |
| `report_date` | 空 | 报告期，可选 |
| `start_year` | `2018` | 起始年份，可选，范围 2000-2100 |
| `end_year` | 当前年份 | 结束年份，可选，范围 2000-2100 |

科创板（688xxx）等部分股票在同花顺摘要源可能数据不全，服务端会自动切换到东方财富 EM 指标源兜底。

`income`、`balancesheet`、`cashflow`、`dividends`、`equity-history`、`freeholders` 使用东方财富 F10 数据中心直连接口，补齐利润表（年初至今/单季）、现金流量表（年初至今/单季）、分红配股、股本变动和十大流通股东等细分数据。

### 宏观

For `kind=forecast` and `kind=express`, omitting `report_date` makes the service scan the latest 8 report periods and return the first period containing rows for the stock. The response `report_date` is the matched period, and `report_dates_checked` lists scanned periods.

```http
GET /macro/china/cpi_monthly
GET /macro/china/cpi_yearly
GET /macro/china/ppi_yearly
GET /macro/china/gdp_yearly
GET /macro/china/pmi_yearly
GET /macro/china/money_supply
GET /macro/chinabond/yield-curve?start_date=2026-01-01&end_date=2026-01-31
```

`/macro/chinabond/yield-curve` 返回中债国债收益率曲线，包含 3 个月、6 个月、1 年、2 年、3 年、5 年、7 年、10 年、15 年、20 年和 30 年期限收益率。

`/macro/china/gdp_yearly`、CPI、PPI、PMI 优先使用 Jin10 数据中心直连源，AKShare 作为兜底。

## ETF

### 实时行情

```http
GET /etfs/premium?sort=abs&limit=50
GET /etfs/premium?sort=premium&limit=50
GET /etfs/510300/premium
GET /etfs/510300/quote
GET /etfs/510300.SH/quote
GET /etfs/159048.SZ/quote
```

返回字段：`fund_code`、`name`、`price`、`change_pct`、`change_amount`、`volume`、`amount`、`open`、`high`、`low`、`pre_close`、`turnover`、`date`、`time`。

`/etfs/premium` 返回场内 ETF 折溢价率列表，字段包含 `premium_discount_rate`、`iopv_realtime_value`、`price`、`amount`、`turnover_rate`、`data_date`、`update_time`。`sort=abs` 按折溢价绝对值排序，`sort=premium` 按最高溢价排序，`sort=discount` 按最大折价排序。

来源顺序（自动轮换）：

1. `eastmoney.push2delay.etf_spot` / `eastmoney.push2delay.etf_premium`
2. `sina.hq.realtime`
3. `eastmoney.push2.etf_quote` / `eastmoney.push2.etf_premium`
4. `akshare.fund_etf_spot_em`
5. `akshare.fund_etf_spot_ths`
6. `akshare.fund_etf_hist_em.latest`

默认缓存 5 分钟。

## 港股

### 沽空记录

```http
GET /hk/stocks/00700/short-selling?limit=100&pages=2
GET /hk/stocks/700/short-selling?limit=50&pages=1
```

返回东方财富港股沽空记录的日度序列，字段包含 `short_volume`、`short_avg_price`、`short_amount_hkd`、`total_turnover_hkd`、`short_turnover_ratio_pct`、`date`。该接口适合观察单只港股沽空占成交比例的趋势，例如腾讯控股 `00700`。

## 美股

### 指数与板块

```http
GET /us/indices?limit=3
GET /us/sectors?limit=5
GET /us/market-summary
```

`/us/indices` 返回道琼斯、纳斯达克、标普 500 三大指数的实时报价，来源顺序：`tencent.qt.us_indices` → `sina.hq.us_indices` → `yahoo.chart.us_indices`。

`/us/sectors` 返回 18 个美股行业/主题 ETF（半导体 XSD、软件 XSW、生物科技 XBI 等）的报价与 A 股板块映射，数据来源：`yahoo.chart.us_sector_etfs`。

`/us/market-summary` 基于 `us_indices` + `us_sectors` 组合，返回隔夜美股盘面摘要，字段包括 `tone`（`offensive`/`balanced`/`neutral`/`cautious`/`defensive`）、`tone_label`、`summary`、`metrics`、`sector_mappings`、`guidance_lines`。适用于 A 股开盘前外盘背景判断，不依赖外部 AI 模型。

### 个股报价与日 K

```http
GET /us/stocks/AAPL/quote
GET /us/stocks/AAPL/daily?days=60
GET /us/stocks/^DJI/quote
GET /us/stocks/TSLA/daily?days=30
```

美股与 A 股是两套独立符号体系：`/stocks/...` 走 A 股（需 `.SH`/`.SZ`），`/us/stocks/...` 走美股（Yahoo/腾讯/新浪代码）。`symbol` 参数支持 Yahoo ticker 格式（`AAPL`、`TSLA`、`^DJI`、`^IXIC`）。

来源顺序（报价）：`yahoo.chart.us_quote` → `sina.hq.us_quote`。

来源顺序（日 K）：`yahoo.chart.us_daily`。

## X / Twitter 时间线

```http
GET /social/x/timeline?accounts=elonmusk,OpenAI&limit=5
GET /social/x/timeline?accounts=@elonmusk&limit=3&hydrate=false
```

- `accounts`：X 账号，逗号分隔（可带或不带 `@`），上限 20 个。
- `limit`：每个账号最多条数（1-10）。
- `hydrate`：是否用帖子链接补充正文/媒体直链，默认 `true`。

来源顺序：`openai_compatible.x_watchlist`（复用 `/search` 的 Grok/OpenAI 兼容模型，实时检索 X 公开推文）→ `x.com.html.timeline`（模型未配置时，直接抓取 X 公开 HTML 兜底，能拿到帖子 ID 与页面标题）。

需要配置 `SEARCH_API_BASE_URL` + `SEARCH_API_KEY`（与 `/search` 共用）以获得模型检索能力；未配置时自动降级到 HTML 兜底。每次请求缓存 5 分钟，timeout 上限 90 秒。

## X / Twitter 时间线

```http
GET /social/x/timeline?accounts=elonmusk,OpenAI&limit=5
GET /social/x/timeline?accounts=@elonmusk&limit=3&hydrate=false
```

- `accounts`：X 账号，逗号分隔（可带或不带 `@`），上限 20 个。
- `limit`：每个账号最多条数（1-10）。
- `hydrate`：是否用帖子链接补充正文/媒体直链，默认 `true`。

来源顺序：`openai_compatible.x_watchlist`（复用 `/search` 的 Grok/OpenAI 兼容模型，实时检索 X 公开推文）→ `x.com.html.timeline`（模型未配置时，直接抓取 X 公开 HTML 兜底，能拿到帖子 ID 与页面标题）。

需要配置 `SEARCH_API_BASE_URL` + `SEARCH_API_KEY`（与 `/search` 共用）以获得模型检索能力；未配置时自动降级到 HTML 兜底。每次请求缓存 5 分钟，timeout 上限 90 秒。

## 管理接口

```http
GET /catalog
GET /cache/stats
POST /cache/purge-expired
POST /cache/purge-all
```

`purge-expired` 只删除已过期缓存，不会删除可用缓存。`purge-all` 删除所有缓存条目（部署新版本后推荐调用一次）。