合约元数据 API¶

概述¶

get_symbols() 用于查询币安合约元数据，数据来源为本地 exchangeInfo.json 快照文件（通过 zer0data ingest-source exchange-info 定期抓取并存储）。支持按市场类型、计价资产过滤，以及排除稳定币底层资产。

功能特性¶

支持 spot（现货）、um（U 本位永续）、cm（币本位永续）三个市场
按计价资产（quoteAsset）过滤，如仅返回 USDT 计价合约
一键排除稳定币底层资产（如 USDC、BUSD 计价的合约）
读取本地快照，无需网络请求，速度快

API 接口¶

`get_symbols()`¶

函数签名¶

client.get_symbols(
    market: str = "um",
    quote_asset: Optional[str] = None,
    exclude_stable_base: bool = False,
) -> pd.DataFrame

等价写法（通过子服务）：

client.symbols.get_symbols(market=..., quote_asset=..., exclude_stable_base=...)

参数说明¶

参数	类型	默认值	说明
`market`	`str`	`"um"`	市场类型：`"spot"`（现货）/ `"um"`（U 本位永续）/ `"cm"`（币本位永续）
`quote_asset`	`str \\| None`	`None`	按计价资产过滤，如 `"USDT"`、`"BTC"`。`None` 表示不过滤，大小写不敏感
`exclude_stable_base`	`bool`	`False`	是否排除底层资产为稳定币的合约（见下方稳定币列表）

稳定币底层资产列表¶

当 exclude_stable_base=True 时，以下 baseAsset 的合约将被过滤：

BKRW、USDC、USDP、TUSD、BUSD、FDUSD、DAI、EUR、GBP、USBP、SUSD、PAXG、AEUR

返回值¶

返回 pd.DataFrame，固定包含以下 6 列：

列名	类型	说明
`symbol`	`str`	合约代码，如 `"BTCUSDT"`
`quoteAsset`	`str`	计价资产，如 `"USDT"`
`onboardDate`	`int`	上线时间戳（毫秒）
`deliveryDate`	`int`	交割时间戳（毫秒），永续合约为远期时间
`underlyingType`	`str`	底层资产类型，如 `"VANILLA"` / `"DEFI"`
`status`	`str`	合约状态，如 `"TRADING"` / `"SETTLING"`

数据时效性

返回的是最近一次 ingest-source exchange-info 抓取时的快照，非实时数据。建议定期更新快照以保持合约列表的准确性。

使用示例¶

查询全部 U 本位永续合约¶

import zer0data as zd

client = zd.Client()

df = client.get_symbols(market="um")
print(f"共 {len(df)} 个 U 本位永续合约")
print(df.head())

仅返回 USDT 计价合约¶

df_usdt = client.get_symbols(market="um", quote_asset="USDT")
print(f"共 {len(df_usdt)} 个 USDT 计价合约")

排除稳定币底层资产¶

# 过滤掉 USDC、BUSD 等稳定币作为 baseAsset 的合约
df_clean = client.get_symbols(
    market="um",
    quote_asset="USDT",
    exclude_stable_base=True,
)
print(f"过滤后剩余 {len(df_clean)} 个合约")

查询现货合约¶

df_spot = client.get_symbols(market="spot", quote_asset="USDT")
print(df_spot[["symbol", "status"]].head(10))

查询币本位永续合约¶

df_cm = client.get_symbols(market="cm")
print(df_cm.head())

直接使用子服务¶

# client.get_symbols(...) 与以下写法完全等价
df = client.symbols.get_symbols(
    market="um",
    quote_asset="USDT",
    exclude_stable_base=True,
)

结合 K 线查询：获取 USDT 合约列表后批量拉取数据¶

import zer0data as zd

client = zd.Client()

# 1. 获取所有活跃的 USDT 永续合约
symbols_df = client.get_symbols(
    market="um",
    quote_asset="USDT",
    exclude_stable_base=True,
)
active_symbols = symbols_df[symbols_df["status"] == "TRADING"]["symbol"].tolist()
print(f"活跃合约数: {len(active_symbols)}")

# 2. 批量查询日线 K 线
df = client.get_kline(
    symbol=active_symbols[:10],  # 示例取前 10 个
    start_date="2024-01-01",
    end_date="2024-01-31",
    frequency="1d",
)
print(df.groupby("symbol").size())

错误处理¶

try:
    df = client.get_symbols(market="fx")  # 不支持的 market
except ValueError as e:
    print(f"参数错误: {e}")
    # ValueError: invalid market: fx

try:
    df = client.get_symbols(market="um", quote_asset="USD$T")  # 非法字符
except ValueError as e:
    print(f"参数错误: {e}")
    # ValueError: invalid quote_asset: USD$T

市场参数取值

market 仅支持 "spot"、"um"、"cm" 三个值，传入其他值时抛出 ValueError。

quote_asset 大小写

quote_asset 参数不区分大小写，"usdt" 与 "USDT" 效果相同。

注意事项¶

数据来源：依赖本地 exchangeInfo.json 快照，而非实时接口
快照目录：Client(data_dir=...) 指定快照所在目录，未传时自动查找项目根目录下 data/exchange_info/
状态过滤：返回结果包含所有状态的合约（含已下线），如需仅保留交易中的合约，请手动过滤 status == "TRADING"

时间戳单位：onboardDate / deliveryDate 为毫秒级 Unix 时间戳，如需转换：

import pandas as pd
df["onboardDate"] = pd.to_datetime(df["onboardDate"], unit="ms")

返回首页： zer0data SDK →