---
name: stock-index-query
description: >-
  Query StockIndex Server for CN/HK/US stock codes, boards, Shenwan industries,
  and ETF/LOF lookup. Use when resolving ticker symbols, listing board or industry
  constituents, searching stocks by name/code, or calling /api/v1 on StockIndex.
---
# StockIndex 证券索引查询

通过 StockIndex Server REST API 查询 A股/港股/美股代码、板块、申万行业与 ETF/LOF。

## 服务地址

读取环境变量 `STOCK_INDEX_BASE_URL`（无尾部斜杠）。API 前缀固定为 `/api/v1`。

## 核心约定

| 项 | 说明 |
|---|---|
| instrumentId | `{MARKET}:{VENUE}.{CODE}`，如 `CN:SH.600519` |
| market | `CN` / `HK` / `US` |
| assetType | `equity` 股票 · `etf` A股 ETF/LOF |
| 分页 | `page` 从 1，`pageSize` 最大 100 |

## 常用流程

### 1. 按名称或代码搜索

```http
GET {BASE}/api/v1/search?q=茅台&market=CN&limit=10
GET {BASE}/api/v1/search?q=510300&assetType=etf
GET {BASE}/api/v1/search?q=CN:SH.600519
```

### 2. 查询单条详情

```http
GET {BASE}/api/v1/stock?code=600519&market=CN
GET {BASE}/api/v1/stock?instrumentId=CN:SH.600519
GET {BASE}/api/v1/stock?code=00700&market=HK
```

代码跨市场歧义时 API 返回 409 + `candidates`，需补 `market` 重试。

### 3. 板块

```http
GET {BASE}/api/v1/boards?market=CN&withCount=1
GET {BASE}/api/v1/boards/detail?board=cyb&market=CN
GET {BASE}/api/v1/boards/stocks?board=cyb&market=CN&page=1&pageSize=50
```

A股板块 key：`etf` `hsj` `cyb` `kcb`；港股：`MB` `GEM` `AH` 等；美股：`tec` `cdr`。

### 4. 行业（申万，A股）

```http
GET {BASE}/api/v1/industries?market=CN&level=1&withCount=1
GET {BASE}/api/v1/industries?market=CN&level=2&parent={一级行业code}
GET {BASE}/api/v1/industries/detail?code=pt01801120
GET {BASE}/api/v1/industries/stocks?code=pt01801120&page=1&pageSize=50
```

### 5. ETF / LOF

```http
GET {BASE}/api/v1/etfs?q=红利&page=1&pageSize=50
GET {BASE}/api/v1/stocks?market=CN&assetType=etf&q=510300
```

## 实现建议

- 使用 `curl` 或脚本 `fetch`，Header：`Accept: application/json`
- 列表接口优先用分页，不要一次拉全量
- 持久化引用用 `instrumentId`，展示用 `code` + `market`
- OpenAPI：`{BASE}/openapi/openapi.yaml`；文档页：`{BASE}/openapi`

## 示例：行业 → 成分股

1. `GET /industries?market=CN&level=1&q=银行&withCount=1` 找到行业 code
2. `GET /industries/stocks?code={industryCode}&page=1&pageSize=100` 取成分股
3. 需要详情时对单只调用 `GET /stock?code=...&market=CN`