---
name: klineshare
description: >-
  Access KlineShare market data (A-share, index, ETF, BJ, metals, futures,
  global index/bond, US stock, plates; realtime, kline, trend, limit-up, LHB,
  moneyflow, suspend) via MCP when available, otherwise HTTP REST with curl.
  Use when the user asks for 行情/K线/涨停/龙虎榜/资金流向/ETF/期货/贵金属/美股/港股,
  or when MCP tools are missing / unsupported by the current agent.
---

# KlineShare 行情（MCP 优先，HTTP 兜底）

## 何时用本 skill

- 用户要查 A 股/指数/ETF/北交所/贵金属/国内期货/全球指数债/美股/港股/站内板块等
- 当前 agent **没有** KlineShare MCP 工具，或 MCP 调用失败
- 需要多页历史 K 线（用 `timestamp` 向前翻页）

## 调用优先级

1. **有 MCP**（工具名如 `get_kline_v2`、`get_realtime`、`get_futures_realtime`）→ 直接调 MCP，结束
2. **无 MCP** → 用下方 HTTP（`curl` + `X-API-Key`）

不要用浏览器自动化代替 API。不要把 API Key 写进回复或提交到 git。

## 鉴权

```bash
export EXT_API_KEY="${EXT_API_KEY:?missing}"
# 必须与签发 Key 的本站一致；勿改用其它入口
BASE_URL="${EXT_API_BASE_URL:-https://klineshare.cn}"
```

Header：`X-API-Key: $EXT_API_KEY`  
公开接口（无需 Key）：`/v1/health`、`/public/v1/catalog`、`/public/v1/indices`、`/public/v1/metals`、`/public/v1/futures`、`/public/v1/futures-v2`、`/public/v1/global-indices`、`/public/v1/global-bonds`、`/public/v1/usstocks`

首次不确定权限时先调 `/v1/me`。若响应含 `api_base`（请求根地址，无尾斜杠），**优先用它作为 `BASE_URL`**，再请求 `{api_base}/v1/...`：

```bash
curl -sS -H "X-API-Key: $EXT_API_KEY" "$BASE_URL/v1/me" | head -c 4000
# 若返回 api_base，则：BASE_URL="<api_base>"
```

## Symbol 与路由（易错，必守）

| 标的 | symbol 示例 | 路径前缀 |
|------|-------------|----------|
| 沪深股票 | `600519.SS`、`000001.SZ` | `/v1/realtime` `/v1/trend` `/v2/kline` |
| 指数 | `000001.SS`、`399001.SZ` | `/v1/index/...`（K 线用 `/v2/index/kline`） |
| 北交所 | `920000.BJ` | K 线：`/v2/kline`（或 `/v1/bj/kline`）；分时：`/v1/bj/trend`（无实时） |
| ETF | `515250.SS`、`159915.SZ` | `/v1/etf/...`（K 线用 `/v2/etf/kline`） |
| 贵金属合约 | `XAU`、`AU9999`、`AU0001` | `/v1/metal/realtime`、`/v2/metal/kline`；清单 `/public/v1/metals` |
| 实物黄金（日更） | 品牌 id 如 `laofengxiang` | `/v1/metal/physical/{brands,products,prices}`（需 `metal_realtime`；非实时） |
| 国内期货 | `AU0001`、`AU2610`、`IF2609` | `/v1/futures/...`、`/v2/futures/kline`；清单 `/public/v1/futures` |
| 国内期货 V2 | 同上；另支持 `GFEX` | `/v1/futures-v2/...`、`/v2/futures-v2/kline`；清单 `/public/v1/futures-v2` |
| 全球指数 | `DJI.GI`、`SPX.GI`、`KS11.GI` | `/v1/global-index/realtime`、`/v1/global-index/trend`、`/v2/global-index/kline`；清单 `/public/v1/global-indices` |
| 国际债券收益率 | `US10Y.GB`、`JP10Y.GB` | `/v1/global-bond/realtime`、`/v2/global-bond/kline`；清单 `/public/v1/global-bonds` |
| 美股 | `AAPL.US`、`TSLA.US` | `/v1/usstock/realtime`、`/v1/usstock/trend`、`/v2/usstock/kline`；清单 `/public/v1/usstocks` |
| 港股 | `00700.HK`、`09988.HK` | `/v1/hkstock/realtime`、`/v1/hkstock/trend`、`/v2/hkstock/kline` |
| 可转债 | `110075.SS` 等 | `/v1/convertible*`、`/v1/bond/realtime`、`/v2/convertible/kline`（勿走个股 `/v1/realtime`） |
| 国债 / 企债 | 见 `/v1/treasuries`、`/v1/enterprises` | `/v1/treasury*`、`/v1/enterprise*`（K 线仍为 `/v1/.../kline`） |
| 站内板块 | 整数 `plate_id`（见 `/v1/catalog/plates`） | `/v1/plate/realtime` `/v1/plate/trend` `/v2/plate/kline`；资金流 `/v1/plate/moneyflow` |

- ETF **禁止**走 `/v1/kline` / `/v1/realtime`（会 400）；用 `/v2/etf/kline` 等
- 指数 **禁止**走个股路径（会 400）；用 `/v1/index/realtime` 等；清单见 `/public/v1/indices`
- 债券 / 全球指数 / 国际债券 / 美股 / 港股 / 贵金属 / 期货 **禁止**与 A 股个股路径混用
- 期货连续主力如 `AU0001`；近月为品种+YYMM（如 `PG2612`）；v1 不含广期所，v2 含 `GFEX`
- 站内板块 **禁止**与新浪资金流板块榜 `/v1/moneyflow/ranking/boards` 混用（后者是 name+category，不是 `plate_id`）
- 板块 K 线仅日 K（`period=86400`）；分时仅当日
- 单券 `/v1/kline`、`/v1/index/kline`、`/v1/etf/kline` **已过时**，请用 `/v2/kline`、`/v2/index/kline`、`/v2/etf/kline`
- 北交所无实时；分时用 `/v1/bj/trend`；K 线可用 `/v2/kline`（或兼容路径 `/v1/bj/kline`）
- 指数 / 贵金属 / 期货 / 全球指数债 K 线复权固定 `none`（或不传复权）
- 自行复权：**推荐** `/v1/adjust-params`（按 `multiplier`/`addend` 计算）；**不建议** `/v1/adjust-factors`

## 常用 HTTP 示例

```bash
# 实时
curl -sS -H "X-API-Key: $EXT_API_KEY" \
  "$BASE_URL/v1/realtime?symbol=600519.SS"

# 日 K v2（period 秒：60/300/900/1800/3600/86400/604800/2592000）
curl -sS -H "X-API-Key: $EXT_API_KEY" \
  "$BASE_URL/v2/kline?symbol=600519.SS&period=86400&adjust_type=forward&count=100&source=live"

# ETF 日 K v2
curl -sS -H "X-API-Key: $EXT_API_KEY" \
  "$BASE_URL/v2/etf/kline?symbol=515250.SS&period=86400&count=100"

# 期货实时 / 日 K
curl -sS -H "X-API-Key: $EXT_API_KEY" \
  "$BASE_URL/v1/futures/realtime?symbols=AU0001,AU2610"
curl -sS -H "X-API-Key: $EXT_API_KEY" \
  "$BASE_URL/v2/futures/kline?symbol=AU0001&period=86400&count=120"

# 涨停池
curl -sS -H "X-API-Key: $EXT_API_KEY" "$BASE_URL/v1/limit-up"

# 龙虎榜日榜
curl -sS -H "X-API-Key: $EXT_API_KEY" "$BASE_URL/v1/lhb/daily"
```

成功体一般是 `{ "success": true, "data": ..., "meta": ... }`。  
失败看 `code`/`message`（401 Key、403 scope、429 限流）。

## 历史 K 线翻页

单次 `count` 有套餐上限。需要更早历史时：

1. 请求一页（建议 `source=hist`；扩展行情无 `source` 时用返回的 `meta.next_timestamp`）
2. 取返回中最早一根 bar 的 `timestamp`（秒）
3. 再请求 `timestamp=<最早-1>`（或 `meta.next_timestamp`），合并去重，直到没有新 bar

详见 [endpoints.md](endpoints.md)「K 线翻页」。

## 工作流建议

**盘面**：`/v1/limit-up` → ladder / plates → 必要时 realtime / moneyflow  
**个股**：stock/corp → realtime → kline → lhb/stock、moneyflow、suspend  
**ETF**：一律 `/v1/etf*` / `/v2/etf/kline`  
**期货**：先 `/public/v1/futures`（或 `futures-v2`）确认代码 → realtime → kline  
**贵金属**：`/public/v1/metals` → `/v1/metal/realtime` / `/v2/metal/kline`

回答时用数据说话：给出关键数字、日期、symbol；不要编造未返回的字段。

## 更多

- 工具 ↔ 路径对照：[endpoints.md](endpoints.md)
- 人类可读文档：https://klineshare.cn/docs
- MCP 接入：https://klineshare.cn/docs/mcp
- 完整接口说明：https://klineshare.cn/llms-full.txt