# 智核API · 用户接入指南

> **版本**：v0.3.0 · **公网地址**：`http://47.119.130.122:39400`
> **更新时间**：2026-09-04

---

## 🎯 这是什么？

**智核API** 是一个 A 股数据中转 API 服务，提供 **241 个数据接口**，覆盖：

- 📊 **竞价数据**（9:25 撮合前后的实时行情）
- 🚀 **涨停分析**（一进二接力、连续涨停、涨停基因）
- 🐉 **龙虎榜**（游资动向、营业部详情）
- 🔍 **个股详情**（财务、行情、资金流、技术指标）
- 📈 **板块行情**（行业轮动、概念追踪）
- 📜 **历史数据**（K线、分时、资金流向）

数据采用多层智能融合 + 自动 fallback 保障高可用。

---

## 🔑 如何获取 API Key？

**请向服务运营方申请**（智核 / 德哥），提供：
- 用途（个人研究 / 商业产品 / 教育研究）
- 预计每日调用量
- 公司/团队（可选）

申请后会获得专属 `X-API-Key`，独立限流配额。

**测试 Key**：可访问 [`/api/test_key`](#) 获取每日 0 点自动重置的测试 Key（50 次/天）。

---

## 📊 限流规则

| Key 类型 | 限流策略 |
|---|---|
| **测试 Key** | 50 次/天（每日 0 点自动重置） |
| **普通 Key** | 60 次/分钟 |
| **年付 Key** | 150 次/分钟 |
| **VIP Key** | 协商配额（通常 1000+ 次/分钟） |

**超限响应**：HTTP 429 + 详细错误信息。

---

## 📖 接口文档

| 文档类型 | URL |
|---|---|
| **Swagger UI**（可交互测试） | http://47.119.130.122:39400/docs |
| **ReDoc**（只读文档） | http://47.119.130.122:39400/redoc |
| **OpenAPI Schema** | http://47.119.130.122:39400/openapi.json |
| **兼容 AI Agent**（龙虾 / Claude Code / Cursor / Cline / Continue / 其他 OpenAPI-aware Agent） | 直接读取 http://47.119.130.122:39400/openapi.json 作为工具描述 |

---

## 💡 快速上手

### 1. 健康检查（公开）

```bash
curl http://47.119.130.122:39400/health
```

返回示例：
```json
{"ok":true,"service":"kore-market","version":"0.3.0"}
```

### 2. 单股实时行情（最常用）

```bash
curl -H "X-API-Key: ***" \
  "http://47.119.130.122:39400/api/kpl/quote?code=***"
```

返回示例：
```json
{"ok":true,"code":"***","name":"上海机场","now_price":23.65,"pct":0.81,"high":23.72,"low":23.32,"open":23.46,"volume":83234,"amount":262,"pe":25.71,"market_cap":588.49,"fetched_at":1787999444}
```

### 3. 一进二涨停接力分析（核心功能）

```bash
curl -H "X-API-Key: ***" \
  "http://47.119.130.122:39400/api/kpl/yijiner/analyze_batch?top_n=5"
```

返回示例：
```json
{"ok":true,"errcode":"0","prev_day":"2026-08-28","today":"2026-08-29","code_count":5,"items":[{"code":"***","name":"昊华科技","price":53.31,"zf_pct":10.01,"lb":"2连板","today_jjzf_pct":10.01,...}]}
```

### 4. 竞价池（9:25 后用）

```bash
curl -H "X-API-Key: ***" \
  "http://47.119.130.122:39400/api/kpl/morning_bidding"
```

### 5. 明天炒什么（主题推荐）

```bash
curl -H "X-API-Key: ***" \
  "http://47.119.130.122:39400/api/kpl/tomorrow_topic?top_n=3"
```

---

## 🐛 错误码对照表

| HTTP 状态 | errcode | 含义 | 建议操作 |
|---|---|---|---|
| 200 | 0 | 成功 | — |
| 401 | 401 | 缺少 API Key | 在 Header 加 `X-API-Key` |
| 403 | 403 | API Key 无效 | 检查 Key 拼写或申请新 Key |
| 403 | 403_expired | API Key 已过期 | 申请续期或新 Key |
| 429 | 429 | 超过限流 | 降频调用或申请更高配额 |
| 400 | 400 | 参数错误（如 code 不是6位） | 检查参数格式 |
| 500 | 500 | 服务器内部错误 | 稍后重试或联系运营方 |

---

## 🛠️ Python 调用示例

```python
import requests

BASE_URL = "http://47.119.130.122:39400"
API_KEY = "***"

headers = {"X-API-Key": API_KEY}

# 单股行情
r = requests.get(
    f"{BASE_URL}/api/kpl/quote",
    params={"code": "***"},
    headers=headers,
    timeout=10,
)
data = r.json()
if data.get("ok"):
    print(f"{data['name']} ({data['code']}): {data['now_price']} 元 ({data['pct']}%)")
else:
    print(f"错误: {data.get('msg')}")

# 一进二分析
r = requests.get(
    f"{BASE_URL}/api/kpl/yijiner/analyze_batch",
    params={"top_n": 5},
    headers=headers,
    timeout=15,
)
for item in r.json().get("items", []):
    print(f"{item['code']} {item['name']} {item['lb']} 封板资金 {item['limit_bid_yuan']/1e8:.1f}亿")
```

---

## 📜 OpenAPI 自动生成客户端

OpenAPI Schema 在 [`/openapi.json`](http://47.119.130.122:39400/openapi.json) 可下载。可以用以下工具自动生成 SDK：

```bash
# Python 客户端
openapi-generator-cli generate \
  -i http://47.119.130.122:39400/openapi.json \
  -g python \
  -o ./kore-market-client/

# TypeScript / JavaScript 客户端
openapi-generator-cli generate \
  -i http://47.119.130.122:39400/openapi.json \
  -g typescript-axios \
  -o ./kore-market-ts-client/

# 在线生成（无需安装）
# https://openapi-generator.tech/
```

---

## ❓ 常见问题

### Q1：数据延迟多少？

实时数据通常 < 1 秒延迟；竞价/涨停数据在 9:25 后立即可用；龙虎榜 T+1 日 18:00 后更新。

### Q2：能获取历史数据吗？

可以，K线支持最近 5 年；分时数据当日；龙虎榜近 30 天。

### Q3：调用频率建议？

- 测试场景：5 次/秒以下
- 生产场景：20 次/秒以下
- 高频场景（>50 次/秒）：需申请 VIP Key

### Q4：怎么知道我的 Key 还有多少配额？

在 Swagger UI 里调用 `/api/kpl/admin/keys/info`（需 master）或自己统计调用次数。

---

## 🆘 技术支持

- **API 问题**：联系服务运营方（智核 / 德哥）
- **紧急故障**：访问 [`/health`](http://47.119.130.122:39400/health) 确认服务状态
- **日志查看**：`journalctl -u kore-market-sz.service -f`（运营方内部）

---

## 📝 服务条款

1. API Key 仅限申请方使用，不得转让或公开
2. 禁止用于违法、欺诈、内幕交易等活动
3. 数据仅供参考，**不构成任何投资建议**
4. 服务运营方保留最终解释权

---

**Powered by 智核API v0.3.0** · 2026-09-04