# Eastmoney 筹码分布接口文档

## 启动服务

```bash
pip install -r requirements.txt
uvicorn eastmoney_spider:app --host 0.0.0.0 --port 8000
```

服务启动后，本机访问地址:

```text
http://127.0.0.1:8000
```

FastAPI 自动文档:

```text
http://127.0.0.1:8000/docs
```

## 接口一: GET 查询筹码分布

```http
GET /chip-distribution?stockCode=688605&endTime=2026-05-24
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| stockCode | string | 是 | 股票代码，例如 `688605` |
| endTime | string | 是 | 查询日期，支持 `YYYY-MM-DD` 或 `YYYYMMDD` |

### curl 示例

```bash
curl "http://127.0.0.1:8000/chip-distribution?stockCode=688605&endTime=2026-05-24"
```

## 接口二: POST 查询筹码分布

```http
POST /chip-distribution
Content-Type: application/json
```

### 请求体

```json
{
  "stockCode": "688605",
  "endTime": "2026-05-24"
}
```

### curl 示例

```bash
curl -X POST "http://127.0.0.1:8000/chip-distribution" ^
  -H "Content-Type: application/json" ^
  -d "{\"stockCode\":\"688605\",\"endTime\":\"2026-05-24\"}"
```

## 返回示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "stock": "1.",
    "stock_code": "688605",
    "end_time": "2026-05-24",
    "trading_day": "2026-05-22",
    "profit_ratio": "62.35%",
    "average_cost": "39.81",
    "p90_cost_range": ["31.20", "48.90"],
    "p90_concentration_ratio": "22.09%",
    "p70_cost_range": ["35.10", "45.30"],
    "p70_concentration_ratio": "12.70%"
  }
}
```

外层字段说明:

| 字段 | 说明 |
| --- | --- |
| code | 业务状态码，`0` 表示成功 |
| message | 状态说明 |
| data | 查询成功时为筹码分布数据，失败时为 `null` |

data 字段说明:

| 字段 | 说明 |
| --- | --- |
| stock | 实际使用的市场前缀，`0.` 为深市，`1.` 为沪市 |
| stock_code | 股票代码 |
| end_time | 请求传入的查询日期 |
| trading_day | 实际使用的 K 线交易日 |
| profit_ratio | 获利比例 |
| average_cost | 平均成本 |
| p90_cost_range | 90% 成本区间 |
| p90_concentration_ratio | 90% 成本区间集中度 |
| p70_cost_range | 70% 成本区间 |
| p70_concentration_ratio | 70% 成本区间集中度 |

## 市场前缀自动识别

接口根据 `stockCode` 前两位自动判定东方财富 secid 的市场前缀，无需用户传入：

| 股票代码前缀 | 市场 | secid 前缀 |
| --- | --- | --- |
| 60 | 沪市主板 | `1.` |
| 68 | 科创板 | `1.` |
| 11 | 沪市可转债 | `1.` |
| 13 | 沪市国债逆回购 | `1.` |
| 5x | 沪市基金 & ETF | `1.` |
| 00 | 深市主板 | `0.` |
| 30 | 创业板 | `0.` |
| 12 | 深市可转债 | `0.` |
| 4x / 8x | 北交所 | `0.` |

## 重试与错误处理

- **网络超时 / HTTP 异常 / 响应格式异常**：`fetch_kline` 会重试 5 次，每次间隔 1 秒。
- **东方财富返回 `data:null`**（极少数情况，例如新规则代码段未覆盖）：触发 `InvalidStockMarketError`，立即抛出，不重试，避免浪费 5 秒。
- **反爬绕过**：底层使用 `curl_cffi` 随机轮换浏览器 TLS 指纹（Chrome / Safari / Edge 等），并挂快代理隧道换出口 IP。

最终失败时接口返回:

```json
{
  "code": 500,
  "message": "失败原因",
  "data": null
}
```