快速开始¶

本指南将带您在几分钟内完成 zer0data SDK 的安装并运行第一个查询。

🏃 5 分钟快速上手¶

第 1 步：安装 SDK¶

本 SDK 已发布到公司内部私有 PyPI 仓库，仅在内网可访问。请确认你已有 Nexus 账号权限。

使用 pip 从私有仓库安装：

pip install -i http://100.119.175.111:8081/repository/pypi-internal/ zer0data

如果你的环境已经通过 pip.conf 等方式配置好了默认私有仓库索引，也可以直接：

pip install zer0data

安装完成后验证：

python -c "import zer0data; print(zer0data.__version__)"

预期输出为一个类似 0.1.0 的版本号，表示 SDK 已成功安装。

第 2 步：初始化 Client¶

import zer0data as zd

# 默认模式：自动查找项目根目录下的 data/exchange_info/
client = zd.Client()

# 自定义 exchange_info 快照目录（独立部署时使用）
client = zd.Client(data_dir="/path/to/exchange_info")

data_dir 说明

data_dir 指向存放 Binance exchangeInfo.json 快照的目录，用于合约元数据查询。如果只使用 K 线查询，可以不传此参数。

第 3 步：查询合约列表¶

# 查询全部 USD-M 永续合约
df = client.get_symbols(market="um")
print(f"共 {len(df)} 个合约")
print(df.head())

输出示例：

共 312 个合约
    symbol quoteAsset  onboardDate deliveryDate underlyingType  status
0  BTCUSDT       USDT   1569888000   4133404800        VANILLA  TRADING
1  ETHUSDT       USDT   1569888000   4133404800        VANILLA  TRADING
...

第 4 步：查询 K 线数据¶

# 查询 BTCUSDT 最近一周的 1h K 线
df = client.get_kline(
    symbol="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-01-07",
    frequency="1h",
)
print(f"共 {len(df)} 行")
print(df.head())

多标的查询

symbol 参数支持传入列表，一次查询多个合约：

df = client.get_kline(
    symbol=["BTCUSDT", "ETHUSDT", "SOLUSDT"],
    start_date="2024-01-01",
    end_date="2024-01-31",
    frequency="1d",
)

📋 环境要求¶

项目	要求
Python	3.11+
DolphinDB 服务	K 线查询必须可访问
exchangeInfo 快照	合约元数据查询必须存在

✅ 安装验证清单¶

python -c "import zer0data" 无报错
Client() 可以正常初始化
get_symbols() 返回非空 DataFrame
get_kline() 返回非空 DataFrame

🎯 下一步¶

📈 K线数据 API — 完整参数说明，分页、字段过滤等高级用法
📋 合约元数据 API — 按市场/计价币种/稳定币过滤合约

准备深入学习？ 查看 K 线数据 API →