快速开始¶

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

🏃 5 分钟快速上手¶

第 1 步：安装 SDK¶

私有 PyPI（推荐）pip（SSH）pip（HTTPS）pip（锁定版本）uv

pip install \
  --index-url http://100.119.175.111:8081/repository/pypi-internal/simple \
  --extra-index-url https://pypi.org/simple \
  --trusted-host 100.119.175.111 \
  zer0data

pip install "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

pip install "git+https://github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

# 推荐用于生产环境，将 <commit> 替换为具体提交 SHA
pip install "git+ssh://git@github.com/zer0coldai/zer0data.git@<commit>#subdirectory=sdk"

uv add "git+ssh://git@github.com/zer0coldai/zer0data.git#subdirectory=sdk"

安装完成后验证：

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

预期输出示例：0.1.3（或更高）

dbmodule 版本要求

从 zer0data>=0.1.3 开始，SDK 依赖的 dbmodule 版本需为 >=0.1.3,<0.2.0。如果你在旧环境中遇到连接到错误 DolphinDB 地址的问题，请执行：

pip install --upgrade zer0data dbmodule
python -c "import zer0data, dbmodule; print(zer0data.__version__, dbmodule.__version__)"

确认两个包的版本组合符合要求后，再运行 get_kline.py 进行验证。

第 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 →

Query Trade Data¶

import zer0data as zd

client = zd.Client()

df = client.get_trade(
    symbol="BTCUSDT",
    start_date="2026-03-01",
    end_date="2026-03-01",
)
print(df.head())

Query Metrics Data¶

import zer0data as zd

client = zd.Client()

df = client.get_metrics(
    symbol="BTCUSDT",
    start_date="2026-03-01",
    end_date="2026-03-01",
)
print(df.head())

Query Fundingfate Data¶

import zer0data as zd

client = zd.Client()

df = client.get_fundingfate(
    symbol="BTCUSDT",
    start_date="2026-03-01",
    end_date="2026-03-02",
)
print(df.head())