alphakit-sdk 0.2.2

AlphaKit — 简洁的金融数据 API 工具包

AlphaKit SDK 使用指南

AlphaKit 是一个简洁的金融数据 API 工具包，提供便捷的 A 股市场数据访问接口。基于 TokenAuth 网关，数据来源于本地缓存与上游 chinadata，自动透传，对用户透明。

快速开始

1. 安装

pip install alphakit-sdk

2. 获取 Token

联系管理员获取您的专属 API Token。Token 仅在创建时显示一次，请妥善保存；如果丢失，管理员可在管理面板"重置 Token"，会保留所有配置生成新 Token。

3. 基础使用

import alphakit as ak

# 设置 token（全局配置，只需设置一次）
ak.set_token('your_token_here')

# 创建 API 客户端
api = ak.AlphaKit()

# 获取股票最近一年的日线数据（智能默认）
df = api.daily(ts_code='000001.SZ')
print(df)

客户端初始化

import alphakit as ak

# 方式1：使用全局 token
ak.set_token('your_token_here')
api = ak.AlphaKit()

# 方式2：实例化时传入 token
api = ak.AlphaKit(token='your_token_here')

# 方式3：自定义服务地址（默认 http://101.42.11.124:38080）
api = ak.AlphaKit(token='your_token_here', base_url='http://your-domain.com')

API 接口说明

股票基础数据

股票列表 - stock_basic

# 获取所有股票基本信息
df = api.stock_basic()

# 获取指定股票信息
df = api.stock_basic(ts_code='000001.SZ')

股票日线行情 - daily ⭐

# 智能默认：只传 ts_code 时，自动获取最近一年的数据（最常用）
df = api.daily(ts_code='000001.SZ')

# 获取指定股票指定日期的行情
df = api.daily(ts_code='000001.SZ', trade_date='20260613')

# 获取指定日期所有股票行情
df = api.daily(trade_date='20260613')

# 获取指定股票时间段行情
df = api.daily(ts_code='000001.SZ', start_date='20260601', end_date='20260630')

返回字段：ts_code, trade_date, open, high, low, close, pre_close, change, pct_chg, vol, amount

每日基础指标 - daily_basic

获取每日估值指标（PE、PB、PS、总市值、换手率等）。

df = api.daily_basic(ts_code='000001.SZ', trade_date='20260613')
df = api.daily_basic(ts_code='000001.SZ', start_date='20260601', end_date='20260630')

资金流向数据

个股资金流向 - moneyflow

df = api.moneyflow(ts_code='000001.SZ', trade_date='20260613')
df = api.moneyflow(ts_code='000001.SZ', start_date='20260601', end_date='20260630')

市场行为数据

停复牌信息 - suspend_d

df = api.suspend_d(ts_code='000001.SZ', start_date='20260601', end_date='20260630')

涨跌停统计 - limit_list_d

df = api.limit_list_d(trade_date='20260613')
df = api.limit_list_d(ts_code='000001.SZ', start_date='20260601', end_date='20260630')

龙虎榜每日明细 - top_list

df = api.top_list(trade_date='20260613')

开盘啦涨停股池 - kpl_list

df = api.query('kpl_list', trade_date='20260613')

ETF 数据

# ETF 列表
df = api.etf_basic()

# ETF 日线行情
df = api.etf_daily(ts_code='510300.SH', trade_date='20260613')
df = api.etf_daily(ts_code='510300.SH', start_date='20260601', end_date='20260630')

# ETF 净值
df = api.etf_nav(ts_code='510300.SH', nav_date='20260613')

# ETF 份额
df = api.etf_share(ts_code='510300.SH', trade_date='20260613')

期权数据

# 期权基础信息
df = api.opt_basic(exchange='SSE')

# 期权日线
df = api.opt_daily(ts_code='10004355.SH', trade_date='20260613')

通用查询接口 - query

对于上述方法未覆盖的接口，使用通用查询：

# 交易日历
df = api.query('trade_cal', exchange='SSE', start_date='20260101', end_date='20261231')

# 复权因子
df = api.query('adj_factor', ts_code='000001.SZ', start_date='20260101', end_date='20260616')

# 融资融券
df = api.query('margin', trade_date='20260613')
df = api.query('margin_detail', ts_code='000001.SZ', trade_date='20260613')

# 行业资金流向
df = api.query('moneyflow_ind_dc', trade_date='20260613')   # 东财行业
df = api.query('moneyflow_ind_ths', trade_date='20260613')  # 同花顺行业
df = api.query('moneyflow_mkt_dc', trade_date='20260613')   # 大盘资金流向

# 申万行业日线
df = api.query('sw_daily', start_date='20260601', end_date='20260616')

# 指数数据
df = api.query('index_basic', market='SSE')
df = api.query('index_dailybasic', ts_code='000001.SH', trade_date='20260613')
df = api.query('index_global', trade_date='20260613')

# 财务数据（按报告期）
df = api.query('income', ts_code='000001.SZ', period='20251231')
df = api.query('balancesheet', ts_code='000001.SZ', period='20251231')
df = api.query('cashflow', ts_code='000001.SZ', period='20251231')
df = api.query('fina_indicator', ts_code='000001.SZ', period='20251231')

# 股票回购
df = api.query('repurchase', ts_code='000001.SZ', start_date='20260101', end_date='20260616')

# 机构调研
df = api.query('stk_surv', ts_code='000001.SZ', start_date='20260101', end_date='20260616')

# 周线/月线
df = api.query('weekly', ts_code='000001.SZ', start_date='20260101', end_date='20260616')
df = api.query('monthly', ts_code='000001.SZ', start_date='20260101', end_date='20260616')

完整示例

示例1：股票基本面 + 行情分析

import alphakit as ak

ak.set_token('your_token_here')
api = ak.AlphaKit()

ts_code = '000001.SZ'

# 基本信息
info = api.stock_basic(ts_code=ts_code)
print("股票信息:")
print(info)

# 最近一年日线
daily_data = api.daily(ts_code=ts_code)  # 默认最近一年
print(f"\n日线数据: {len(daily_data)} 条")
print(daily_data.head())

# 估值指标
valuation = api.daily_basic(ts_code=ts_code, start_date='20260101', end_date='20260616')
print(f"\n估值数据: {len(valuation)} 条")
print(valuation[['trade_date', 'pe', 'pb', 'total_mv']].head())

示例2：每日市场扫描

import alphakit as ak

ak.set_token('your_token_here')
api = ak.AlphaKit()

trade_date = '20260613'

# 涨跌停统计
limit_stats = api.limit_list_d(trade_date=trade_date)
print(f"涨跌停股票数: {len(limit_stats)}")

# 龙虎榜
top_stocks = api.top_list(trade_date=trade_date)
print(f"龙虎榜股票数: {len(top_stocks)}")

# 开盘啦涨停池
kpl = api.query('kpl_list', trade_date=trade_date)
print(f"开盘啦涨停: {len(kpl)} 只")

示例3：ETF 组合分析

import alphakit as ak

ak.set_token('your_token_here')
api = ak.AlphaKit()

# ETF 列表
etf_list = api.etf_basic()
print(f"ETF 总数: {len(etf_list)}")

ts_code = '510300.SH'

# 日线 + 净值
etf_daily = api.etf_daily(ts_code=ts_code, start_date='20260101', end_date='20260616')
etf_nav = api.etf_nav(ts_code=ts_code, start_date='20260101', end_date='20260616')

print(f"\n{ts_code} 行情:")
print(etf_daily[['trade_date', 'close', 'vol', 'amount']].head())

print(f"\n{ts_code} 净值:")
print(etf_nav[['nav_date', 'unit_nav', 'accum_nav']].head())

示例4：财务指标对比

import alphakit as ak
import pandas as pd

ak.set_token('your_token_here')
api = ak.AlphaKit()

# 获取 2025 年报数据
ts_codes = ['000001.SZ', '000002.SZ', '600000.SH']
results = []

for code in ts_codes:
    df = api.query('fina_indicator', ts_code=code, period='20251231')
    if not df.empty:
        results.append(df)

if results:
    combined = pd.concat(results, ignore_index=True)
    print(combined[['ts_code', 'eps', 'roe', 'netprofit_yoy']])

错误处理

import alphakit as ak
from alphakit.exceptions import AlphaKitError

ak.set_token('your_token_here')
api = ak.AlphaKit()

try:
    df = api.daily(ts_code='000001.SZ', trade_date='20260613')
    print(f"获取成功: {len(df)} 条数据")
except AlphaKitError as e:
    print(f"API 错误 [{e.code}]: {e.message}")
except Exception as e:
    print(f"其他错误: {e}")

错误码说明

错误码	HTTP	说明	解决方案
1001	401	Token 缺失/无效/吊销/过期	检查 Token 是否正确，是否已过期
1002	403	当前等级无权访问该接口	联系管理员升级等级
1003	403	IP 限制（封禁或超过绑定上限）	联系管理员检查 IP 绑定
1004	429	触发限频（每分钟请求次数过多）	降低请求频率，稍后重试
1005	429	当日配额已用尽	等待次日重置或联系管理员提升配额
1006	400	请求参数错误	检查参数名和值是否正确
1500	500	服务器内部错误	联系管理员排查
9999	-	网络请求失败（SDK 端）	检查网络和服务地址

最佳实践

1. Token 安全管理

import os
import alphakit as ak

# 从环境变量读取 token（推荐，避免硬编码）
token = os.getenv('ALPHAKIT_TOKEN')
if not token:
    raise RuntimeError('请设置环境变量 ALPHAKIT_TOKEN')

ak.set_token(token)
api = ak.AlphaKit()

2. 利用智能默认

# ❌ 不必要的样板代码
from datetime import datetime, timedelta
end = datetime.now().strftime('%Y%m%d')
start = (datetime.now() - timedelta(days=365)).strftime('%Y%m%d')
df = api.daily(ts_code='000001.SZ', start_date=start, end_date=end)

# ✅ 使用智能默认
df = api.daily(ts_code='000001.SZ')  # 自动取最近一年

3. 批量查询优化

import alphakit as ak

ak.set_token('your_token_here')
api = ak.AlphaKit()

# 优先使用日期范围批量获取，减少请求次数
# ❌ 不推荐：逐日查询
for d in date_list:
    df = api.daily(ts_code='000001.SZ', trade_date=d)

# ✅ 推荐：一次取整段
df = api.daily(ts_code='000001.SZ', start_date='20260101', end_date='20260616')

# 多股票场景，控制并发避免触发限频
import time
stock_codes = ['000001.SZ', '000002.SZ', '600000.SH']
results = [api.daily(ts_code=c) for c in stock_codes]
# 默认每分钟 60 次限频，正常使用不会触发

4. 数据缓存

import alphakit as ak
import pickle
from pathlib import Path

ak.set_token('your_token_here')
api = ak.AlphaKit()

cache_dir = Path('data_cache')
cache_dir.mkdir(exist_ok=True)

def get_cached(cache_file, fetch_func, *args, **kwargs):
    """带缓存的数据获取"""
    cache_path = cache_dir / cache_file
    if cache_path.exists():
        with open(cache_path, 'rb') as f:
            return pickle.load(f)
    data = fetch_func(*args, **kwargs)
    with open(cache_path, 'wb') as f:
        pickle.dump(data, f)
    return data

# 用法：股票列表变化少，适合缓存
df = get_cached('stock_basic.pkl', api.stock_basic)

5. 异常重试

import alphakit as ak
from alphakit.exceptions import AlphaKitError
import time

def safe_query(func, *args, max_retries=3, **kwargs):
    """带指数退避的安全查询"""
    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except AlphaKitError as e:
            # 限频和服务器错误才重试，认证错误直接抛出
            if e.code in (1004, 1500, 9999) and attempt < max_retries - 1:
                wait = 2 ** attempt
                print(f"重试 {attempt + 1}/{max_retries}（{wait}秒后）: {e.message}")
                time.sleep(wait)
            else:
                raise
    return None

# 使用
ak.set_token('your_token_here')
api = ak.AlphaKit()
df = safe_query(api.daily, ts_code='000001.SZ')

数据范围

• 日线行情、估值指标、资金流向、龙虎榜、涨跌停：自 2020-01-02 起，每个交易日 18:00 自动更新
• 指数日线：每个交易日更新（部分历史数据可能不完整）
• 财务数据：按季度更新（季度末日期：03-31, 06-30, 09-30, 12-31）
• ETF 数据：每个交易日更新
• 期权数据：每个交易日更新

服务架构

你的代码
   ↓ HTTPS
AlphaKit SDK (Python 客户端)
   ↓ POST /api/v1/query
TokenAuth 网关 (Token 验证 + 限流 + IP 绑定)
   ↓
本地数据缓存 (PostgreSQL) ← 大部分请求命中缓存
   ↓ 未命中时透传
chinadata 上游 API

技术支持

• 文档：本文档（最新版本）
• 问题反馈：联系管理员
• 配额查询：联系管理员或访问管理后台

版本历史

v0.2.1（2026-06）

• daily() 新增智能默认：只传 ts_code 时自动取最近一年数据
• 修复默认 base_url（改为 38080 端口）
• 修复 daily API 与本地缓存表（stock_daily）的映射

v0.2.0

• 支持 ETF、期权等更多数据接口
• 优化错误处理

v0.1.0

• 初始版本
• 支持基础股票数据接口

许可证

MIT License