Metadata-Version: 2.4
Name: alphafeed
Version: 0.1.3
Summary: AlphaFeed Python SDK
Author: AlphaFeed
License: MIT
Project-URL: Documentation, https://docs.alphafeed.org
Keywords: finance,stock,market-data,quant,kline,alphafeed,a-share,us-stock,hk-stock,real-time-quotes
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: tqdm>=4.60.0

# AlphaFeed Python SDK

AlphaFeed Python SDK 是 AlphaFeed 金融市场数据 API 的 Python 客户端，支持 A 股、ETF、美股、港股。

> **完整文档**：<https://docs.alphafeed.org>

---

## 安装

```bash
pip install alphafeed
```

SDK 支持 Python 3.9+，推荐 3.10 或更高版本。内置 pandas 和 tqdm 支持。

---

## 初始化

```python
from alphafeed import AlphaFeed

af = AlphaFeed(api_key="your-api-key")
```

也支持环境变量：

```bash
export ALPHAFEED_API_KEY="your-api-key"
```

```python
from alphafeed import AlphaFeed
af = AlphaFeed()  # 自动读取 ALPHAFEED_API_KEY
```

---

## 标的代码格式

| 示例 | 说明 |
|------|------|
| `600519.SH` | 上交所 |
| `000001.SZ` | 深交所 |
| `AAPL.US` | 美股 |
| `00700.HK` | 港股 |

---

## 基础用法

### K 线获取

```python
from alphafeed import AlphaFeed

af = AlphaFeed(api_key="your-api-key")

# 日 K 线，返回 DataFrame
df = af.klines.get("600519.SH", period="1d", count=5, to_dataframe=True)
print(df[["trade_date", "open", "high", "low", "close", "volume"]])
#    trade_date     open     high      low    close  volume
# 0  2026-06-02  1306.00  1326.36  1301.00  1307.22   36362
# 1  2026-06-03  1304.00  1304.00  1276.00  1281.91   52477
# 2  2026-06-04  1278.99  1288.99  1266.69  1268.00   33506
# 3  2026-06-05  1278.00  1283.00  1267.74  1272.86   31304
# 4  2026-06-08  1272.00  1278.00  1260.00  1262.98   30828

# 比例前复权（默认）/ 比例后复权 / 差值前复权 / 差值后复权 / 不复权
df = af.klines.get("600519.SH", adjust="forward", to_dataframe=True)
df = af.klines.get("600519.SH", adjust="backward", to_dataframe=True)
df = af.klines.get("600519.SH", adjust="forward_additive", to_dataframe=True)
df = af.klines.get("600519.SH", adjust="backward_additive", to_dataframe=True)
df = af.klines.get("600519.SH", adjust="none", to_dataframe=True)
```

**批量获取**：多只标的一次拉取：

```python
symbols = ["600519.SH", "000001.SZ", "601318.SH"]
dfs = af.klines.batch(symbols, period="1d", count=5, to_dataframe=True, show_progress=True)
# dfs 是 dict: {"600519.SH": DataFrame, "000001.SZ": DataFrame, ...}
print(dfs["600519.SH"][["trade_date", "close"]])
```

### 日内分时

```python
# 当日 1 分钟线
df = af.klines.intraday("600519.SH", to_dataframe=True)
print(df[["trade_time", "close", "volume"]].tail())
#               trade_time    close  volume
# 236  2026-06-08 14:56:00  1263.00     191
# 237  2026-06-08 14:57:00  1262.99     126
# 238  2026-06-08 14:58:00  1263.00       6
# 239  2026-06-08 14:59:00  1263.00       0
# 240  2026-06-08 15:00:00  1262.98     254

# 5 分钟线
df = af.klines.intraday("600519.SH", period="5m", to_dataframe=True)

# 批量日内分时
dfs = af.klines.intraday_batch(["600519.SH", "000001.SZ"], to_dataframe=True)
```

### 实时行情

**按标的代码查询**

```python
df = af.quotes.get(symbols=["600519.SH", "000001.SZ"], to_dataframe=True)
print(df[["symbol", "last_price", "volume", "ext.name", "ext.change_pct"]])
#       symbol  last_price   volume ext.name  ext.change_pct
# 0  000001.SZ       11.03  1090926     平安银行        0.004554
# 1  600519.SH     1262.98    30828     贵州茅台       -0.007762
```

**按标的池查询（全量行情）**

```python
# 全部 A 股实时行情
df = af.quotes.get(universes="CN_Stock", to_dataframe=True)
print(f"共 {len(df)} 只标的")

# 全部 ETF 行情
df = af.quotes.get(universes="CN_ETF", to_dataframe=True)
```

支持的标的池：`CN_Stock`（A股）、`US_Stock`（美股）、`HK_Stock`（港股）、`CN_ETF`（ETF）

### 五档盘口

```python
depth = af.depth.get("600519.SH")
print(f"标的: {depth['symbol']}, 地区: {depth['region']}")
print(f"买盘价: {depth['bid_prices']}")   # [1262.98, 1262.65, ...]
print(f"买盘量: {depth['bid_volumes']}")  # [2, 1, ...]
print(f"卖盘价: {depth['ask_prices']}")   # [1262.99, 1263.0, ...]
print(f"卖盘量: {depth['ask_volumes']}")  # [7, 44, ...]
```

### 标的信息

```python
# 单个标的
inst = af.instruments.get("600519.SH")
print(f"{inst['symbol']}: {inst['name']} ({inst['exchange']}, {inst['type']})")
# 600519.SH: 贵州茅台 (SH, stock)
print(f"上市日期: {inst['ext']['listing_date']}")
# 上市日期: 2001-08-27

# 批量查询
insts = af.instruments.batch(["600519.SH", "000001.SZ", "00700.HK"])
for i in insts:
    print(f"{i['symbol']}: {i['name']} ({i['region']})")
# 600519.SH: 贵州茅台 (CN)
# 000001.SZ: 平安银行 (CN)
# 00700.HK: 腾讯控股 (HK)
```

### 复权因子

```python
df = af.klines.ex_factors(["600519.SH", "000001.SZ"], to_dataframe=True)
print(df[["symbol", "trade_date", "ex_factor"]].tail())
#        symbol  trade_date  ex_factor
# 52  000001.SZ  2023-06-14   1.024369
# 53  000001.SZ  2024-06-14   1.071428
# 54  000001.SZ  2024-10-10   1.021872
# 55  000001.SZ  2025-06-12   1.031331
# 56  000001.SZ  2025-10-15   1.021505
```

---

## 更多文档

- [Python SDK 快速开始](https://docs.alphafeed.org/zh-Hans/sdk/python-quickstart)
- [使用示例](https://docs.alphafeed.org/zh-Hans/sdk/python-examples)
- [REST API 说明](https://docs.alphafeed.org/zh-Hans/api-reference/introduction)

---

## License

MIT
