367 lines
10 KiB
Markdown
367 lines
10 KiB
Markdown
# A股市场数据API工具
|
||
|
||
`股票数据` `A股` `可转债` `ETF` `实时行情` `Python`
|
||
|
||
# 股票数据 API Skill for OpenClaw
|
||
|
||
这是一个为 OpenClaw 等 Agent 工具设计的股票数据 Skill，提供了 A 股市场及周边资产的完整数据访问能力。
|
||
|
||
## 📥 安装方法
|
||
|
||
```bash
|
||
npx skills add https://github.com/1018466411/openclaw-stock-data-skill
|
||
```
|
||
|
||
安装时按提示选择：
|
||
1. 选择 **openclaw**
|
||
2. 选择 **global** 应用于所有 Agent
|
||
3. 复制到所有 Agent：**yes**
|
||
|
||
## 📋 数据分类概览
|
||
|
||
2. **股票实时数据**
|
||
- 实时行情快照（价格、五档盘口等）、集合竞价、推送历史、停牌信息等
|
||
- 典型函数：`get_stock_snapshot_daily`（实时快照）、`get_call_auction`、`get_basic_snapshot`（集合竞价快照）、`get_stock_snapshot_push_history` 等
|
||
|
||
3. **股票历史数据**
|
||
- 日 K 线（前复权/不复权）、分钟级历史、日度财务因子、复权因子、历史快照等
|
||
- 典型函数：`get_daily_data`、`get_history_data`、`get_finance_data`、`get_daily_adj_data`、`get_adj_factor` 等
|
||
|
||
3. **可转债历史和实时数据**
|
||
- 可转债日线、分钟级行情、日度指标（纯债价值、转股溢价等）、收盘快照、基础列表等
|
||
- 典型函数：`get_bond_daily`、`get_bond_history`、`get_bond_indicator_daily`、`get_bond_closing_snapshot`、`get_bond_list` 等
|
||
|
||
4. **ETF 数据**
|
||
- ETF 列表数据
|
||
- ETF 日线与分钟级历史行情
|
||
- 典型函数：`get_etf_list`、`get_etf_daily`、`get_etf_history`
|
||
|
||
5. **指数历史数据**
|
||
- 指数分钟级历史行情（支持多种时间粒度）
|
||
- 典型函数：`get_index_history`
|
||
|
||
6. **龙虎榜数据**
|
||
- 龙虎榜机构明细数据
|
||
- 典型函数：`get_dragon_tiger`
|
||
|
||
7. **WebSocket 实时快照**
|
||
- 通过 WebSocket 协议实时推送全市场股票快照
|
||
- 支持 Gzip 压缩，JSON 格式，字段简写（cd, lp, vo 等）
|
||
- 连接地址：`wss://data.diemeng.chat/ws/stock/snapshot?token=YOUR_API_KEY`
|
||
|
||
> 此外还提供**条件搜索等高级能力**，详见 `stock_api.py` 与 `skill.json`。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 注册账号并开通接口权限
|
||
|
||
**重要：使用本 Skill 前，必须先注册账号并为需要使用的接口开通对应权限。**
|
||
|
||
1. 访问 [https://data.diemeng.chat/](https://data.diemeng.chat/)
|
||
2. 注册新账号或登录现有账号
|
||
3. 在**个人中心 / 权限或套餐管理**中，按需开通以下数据大类的访问权限：
|
||
- 股票历史数据（行情、财务、估值等）
|
||
- 股票实时数据（集合竞价、基础快照等）
|
||
- 可转债数据（历史 & 实时）
|
||
- ETF 数据
|
||
- 指数历史数据
|
||
4. 在 **API 管理**中创建并复制您的 **API Key**
|
||
|
||
> 如果未为某一类接口开通权限，即使配置了 API Key，也会收到 403 或权限不足的错误。
|
||
|
||
### 2. 在 Skill 页面配置 API Key（推荐）
|
||
|
||
在 OpenClaw / ClawHub 中启用本 Skill 时：
|
||
|
||
1. 打开 `openclaw-stock-skill` 的 Skill 配置页面
|
||
2. 在参数面板中将从 `data.diemeng.chat` 获取的 **API Key** 填入对应字段（通常是 `apiKey` 或 `STOCK_API_KEY`）
|
||
3. 保存后，网关会自动将该值注入到运行环境中（映射为 `STOCK_API_KEY` 环境变量）
|
||
|
||
这样使用本 Skill 时，无需在本机手动配置环境变量。
|
||
|
||
### 3. （可选）在本地代码中直接使用 API Key
|
||
|
||
如果你在自己的 Python 项目中直接使用 `stock_api.py`，可以按以下方式配置：
|
||
|
||
#### 方式一：配置文件（推荐用于 Linux 无界面环境）
|
||
|
||
在代码同级目录下创建一个名为 `config.json` 的文件（可复制 `config.json.template`），内容如下：
|
||
|
||
```json
|
||
{
|
||
"api_key": "your_api_key_here"
|
||
}
|
||
```
|
||
|
||
#### 方式二：环境变量
|
||
|
||
```bash
|
||
# Linux/macOS
|
||
export STOCK_API_KEY="your_api_key_here"
|
||
|
||
# Windows PowerShell
|
||
$env:STOCK_API_KEY="your_api_key_here"
|
||
|
||
# Windows CMD
|
||
set STOCK_API_KEY=your_api_key_here
|
||
```
|
||
|
||
#### 方式三：在代码中设置
|
||
|
||
```python
|
||
import os
|
||
os.environ["STOCK_API_KEY"] = "your_api_key_here"
|
||
```
|
||
|
||
### 4. 安装依赖
|
||
|
||
```bash
|
||
pip install requests
|
||
```
|
||
|
||
或使用 requirements.txt：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 📖 使用示例
|
||
|
||
### 基本使用
|
||
|
||
```python
|
||
from stock_api import get_stock_list, get_daily_data, search_stock_by_name
|
||
|
||
# 1. 获取股票列表
|
||
stocks = get_stock_list(page_size=10)
|
||
print(f"共有 {stocks['total']} 只股票")
|
||
for stock in stocks['list']:
|
||
print(f"{stock['stock_code']}: {stock['name']}")
|
||
|
||
# 2. 搜索股票
|
||
results = search_stock_by_name("平安")
|
||
for stock in results:
|
||
print(f"{stock['stock_code']}: {stock['name']}")
|
||
|
||
# 3. 获取日K线数据
|
||
daily_data = get_daily_data(
|
||
stock_code="600000.SH",
|
||
start_time="2024-01-01",
|
||
end_time="2024-01-31"
|
||
)
|
||
print(f"共 {daily_data['total']} 条数据")
|
||
for record in daily_data['list'][:5]:
|
||
print(f"{record['trade_date']}: 收盘价 {record['close']}")
|
||
```
|
||
|
||
### 获取多只股票数据
|
||
|
||
```python
|
||
from stock_api import get_daily_data
|
||
|
||
# 同时查询多只股票
|
||
data = get_daily_data(
|
||
stock_code=["600000.SH", "000001.SZ", "000002.SZ"],
|
||
start_time="2024-01-01",
|
||
end_time="2024-01-31"
|
||
)
|
||
```
|
||
|
||
### 获取历史分时数据（股票分钟级）
|
||
|
||
```python
|
||
from stock_api import get_history_data
|
||
|
||
# 获取5分钟级别数据
|
||
data = get_history_data(
|
||
stock_code="600000.SH",
|
||
level="5min",
|
||
start_time="2024-01-15 09:30:00",
|
||
end_time="2024-01-15 15:00:00"
|
||
)
|
||
```
|
||
|
||
### 获取当天分时数据（全市场实时）
|
||
|
||
```python
|
||
from stock_api import get_realtime_history
|
||
|
||
# 建议使用定时任务按时间拉取，一次获取全市场一分钟的数据
|
||
# 定时任务建议在每分钟的 2-5 秒后拉取上一分钟数据，15秒后可复拉一次确保准确性
|
||
data = get_realtime_history(
|
||
trade_time="2026-03-15 09:31:00"
|
||
)
|
||
```
|
||
|
||
### 获取财务数据（股票日度因子）
|
||
|
||
```python
|
||
from stock_api import get_finance_data
|
||
|
||
# 获取财务指标
|
||
finance = get_finance_data(
|
||
stock_code="600000.SH",
|
||
start_time="2024-01-01",
|
||
end_time="2024-01-31"
|
||
)
|
||
|
||
for record in finance['list']:
|
||
print(f"日期: {record['trade_date']}")
|
||
print(f"PE(TTM): {record['pe_ttm']}")
|
||
print(f"PE百分位: {record.get('pe_ttm_percentile')}%")
|
||
print(f"PB: {record['pb']}")
|
||
print(f"总市值: {record['total_mv']}")
|
||
```
|
||
|
||
### 获取可转债数据
|
||
|
||
```python
|
||
from stock_api import (
|
||
get_bond_daily,
|
||
get_bond_history,
|
||
get_bond_indicator_daily,
|
||
)
|
||
|
||
# 1. 获取可转债日线数据
|
||
daily = get_bond_daily(
|
||
stock_code="110031.SH",
|
||
start_time="2024-01-01",
|
||
end_time="2024-01-31",
|
||
)
|
||
|
||
# 2. 获取可转债 5 分钟级历史数据
|
||
history = get_bond_history(
|
||
stock_code="110031.SH",
|
||
level="5min",
|
||
start_time="2024-01-02 09:30:00",
|
||
end_time="2024-01-02 15:00:00",
|
||
)
|
||
|
||
# 3. 获取可转债日度指标（纯债价值、转股溢价等）
|
||
indicator = get_bond_indicator_daily(
|
||
stock_code="110031.SH",
|
||
start_date="2024-01-01",
|
||
end_date="2024-01-31",
|
||
)
|
||
```
|
||
|
||
### 获取 ETF 数据
|
||
|
||
```python
|
||
from stock_api import get_etf_list, get_etf_daily, get_etf_history
|
||
|
||
# 1. 获取 ETF 列表
|
||
etf_list = get_etf_list()
|
||
print(etf_list)
|
||
|
||
# 2. 获取 ETF 日线数据
|
||
etf_daily = get_etf_daily(
|
||
stock_code="510300.SH",
|
||
start_time="2024-01-01",
|
||
end_time="2024-01-31",
|
||
)
|
||
|
||
# 3. 获取 ETF 5 分钟级历史数据
|
||
etf_history = get_etf_history(
|
||
stock_code="510300.SH",
|
||
level="5min",
|
||
start_time="2024-01-02 09:30:00",
|
||
end_time="2024-01-02 15:00:00",
|
||
)
|
||
```
|
||
|
||
### 获取指数历史数据
|
||
|
||
```python
|
||
from stock_api import get_index_history
|
||
|
||
# 获取指数 1 分钟级历史数据
|
||
index_history = get_index_history(
|
||
index_code="000300.SH", # 沪深 300 指数
|
||
level="1min",
|
||
start_time="2024-01-02 09:30:00",
|
||
end_time="2024-01-02 15:00:00",
|
||
)
|
||
```
|
||
|
||
## 🔧 API 接口说明
|
||
|
||
### 股票代码格式
|
||
|
||
- 上海：`600000.SH`、`688000.SH`
|
||
- 深圳：`000001.SZ`、`300000.SZ`
|
||
- 北京：`430000.BJ`、`830000.BJ`
|
||
|
||
### 时间格式
|
||
|
||
- 日期：`YYYY-MM-DD`，例如 `2024-01-15`
|
||
- 日期时间：`YYYY-MM-DD HH:MM:SS`，例如 `2024-01-15 09:30:00`
|
||
|
||
### 分时级别
|
||
|
||
- `1min` - 1 分钟
|
||
- `5min` - 5 分钟（默认）
|
||
- `15min` - 15 分钟
|
||
- `30min` - 30 分钟
|
||
- `60min` - 60 分钟
|
||
|
||
## 📚 完整 API 文档
|
||
|
||
更多详细的 API 文档请访问：[https://data.diemeng.chat/](https://data.diemeng.chat/)
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **API Key 安全**：请妥善保管您的 API Key，不要将其提交到公开代码仓库
|
||
2. **请求频率**：请注意 API 的请求频率限制，避免过于频繁的请求
|
||
3. **数据范围**：部分接口支持查询全市场数据，但建议使用分页参数控制返回数量
|
||
4. **错误处理**：所有函数在出错时会抛出异常，请做好异常处理
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q：提示"未找到 API Key"
|
||
|
||
A：请确保已设置环境变量 `STOCK_API_KEY`，或访问 [https://data.diemeng.chat/](https://data.diemeng.chat/) 注册并获取 API Key。
|
||
|
||
### Q：返回 401 未授权错误
|
||
|
||
A：请检查 API Key 是否正确，并确保已在个人中心激活 API 访问权限。
|
||
|
||
### Q：返回 403 权限不足
|
||
|
||
A：您的账号可能没有访问该接口的权限，请检查您的账号权限设置。
|
||
|
||
### Q：如何获取更多数据？
|
||
|
||
A：使用 `page` 和 `page_size` 参数进行分页查询，或联系管理员提升账号权限。
|
||
|
||
## 📝 更新日志
|
||
|
||
### v1.0.0 (2024-01-XX)
|
||
- 初始版本发布
|
||
- 支持股票列表、日K线、历史分时、财务数据等核心功能
|
||
- 支持股票搜索查询
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
## 🔗 相关链接
|
||
|
||
- API 文档：[https://data.diemeng.chat/](https://data.diemeng.chat/)
|
||
- 注册账号：[https://data.diemeng.chat/](https://data.diemeng.chat/)
|
||
- GitHub 仓库：[查看项目源码](https://github.com)（创建仓库后更新此链接）
|
||
- GitHub 推送指南：[GITHUB.md](./GITHUB.md)
|
||
|
||
## 📤 推送到 GitHub
|
||
|
||
**建议推送到 GitHub！** OpenClaw 有官方的 Skills 生态，你可以：
|
||
|
||
1. **推送到个人 GitHub 仓库** - 便于版本控制和分享
|
||
2. **提交到 OpenClaw Skills 生态** - 让更多用户发现和使用你的 Skill
|
||
3. **通过 ClawHub 平台发布** - OpenClaw 的官方 Skills 管理平台
|
||
|
||
详细步骤请查看 [GITHUB.md](./GITHUB.md) 文件。
|
||
|
||
---
|
||
|
||
**重要提示**：使用本 Skill 前，请务必访问 [https://data.diemeng.chat/](https://data.diemeng.chat/) 注册并获取 API Key！ |