Metadata-Version: 2.4
Name: alphakit-sdk
Version: 0.1.1
Summary: AlphaKit — 简洁的金融数据 API 工具包
Author: AlphaKit Team
License: MIT
Project-URL: Homepage, https://github.com/yourusername/alphakit
Keywords: finance,data,api,quant,alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.3.0

# AlphaKit

简洁的金融数据 API 工具包，提供类似 tushare 的使用体验。

## 安装

```bash
pip install alphakit-sdk
```

本地开发安装：
```bash
cd TokenAuth
pip install -e .
```

## 快速开始

### 方式一：全局 token（推荐）

```python
import alphakit as ak

# 设置全局 token
ak.set_token('your_token_here')

# 创建 API 实例
api = ak.AlphaKit()

# 查询数据
df = api.daily_basic(trade_date='20260101')
print(df.head())
```

### 方式二：实例化时传入 token

```python
from alphakit import AlphaKit

api = AlphaKit(token='your_token_here')
df = api.opt_daily(ts_code='10004355.SH', start_date='20260101', end_date='20260131')
```

### 方式三：自定义服务器地址

```python
import alphakit as ak

ak.set_token('your_token')
api = ak.AlphaKit(base_url='http://your-server.com:8002')
df = api.etf_daily(ts_code='510050.SH', trade_date='20260101')
```

## API 方法

所有方法返回 pandas DataFrame。

### 日线基础数据
```python
df = api.daily_basic(
    ts_code='000001.SZ',      # 可选
    trade_date='20260101',    # 可选
    start_date='20260101',    # 可选
    end_date='20260131'       # 可选
)
```

### 期权数据
```python
# 期权基础信息
df = api.opt_basic(ts_code='10004355.SH')

# 期权日线
df = api.opt_daily(
    ts_code='10004355.SH',
    start_date='20260101',
    end_date='20260131'
)
```

### ETF 数据
```python
# ETF 基础信息
df = api.etf_basic(market='SSE')

# ETF 日线
df = api.etf_daily(ts_code='510050.SH', trade_date='20260101')

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

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

# ETF 主题
df = api.etf_theme_map(theme='科技')
```

### 通用查询（支持所有表）
```python
df = api.query('daily_basic', ts_code='000001.SZ', trade_date='20260101')
```

## 错误处理

```python
from alphakit import AlphaKit, AlphaKitError

api = AlphaKit(token='your_token')

try:
    df = api.daily_basic(trade_date='20260101')
except AlphaKitError as e:
    print(f"错误码: {e.code}")
    print(f"错误信息: {e.message}")
```

常见错误码：
- `1001`: Token 无效 / 过期 / 吊销
- `1002`: 无权限访问该表
- `1003`: IP 超限 / 封禁
- `1004`: 每分钟限频
- `1005`: 每日配额用尽
- `1006`: 查询参数错误

## 注意事项

1. **大表必须带过滤条件**：`daily_basic`、`opt_daily`、`etf_daily` 等大表必须带 `ts_code` 或日期过滤，否则报错 1006
2. **日期格式**：`YYYYMMDD`（如 `20260101`）
3. **IP 限制**：每个 token 默认最多绑定 3 个 IP，超限拒绝
4. **限流配额**：默认每分钟 60 次、每日 500 次

## 示例脚本

```python
import alphakit as ak

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

# 查某股票某天的数据
df = api.daily_basic(ts_code='000001.SZ', trade_date='20260101')
print(df)

# 查某期权某月的行情
df = api.opt_daily(ts_code='10004355.SH', start_date='20260101', end_date='20260131')
print(df.tail())

# 查所有 ETF 基础信息（小表可不带过滤）
df = api.etf_basic()
print(f"共 {len(df)} 只 ETF")
```
