# Binance 数据 (/zh/features/data/binance-data)

如何将 Binance 历史数据导入 Python？`vbt.BinanceData` 从 Binance 公共 API 下载现货和期货市场 K
线，包括成交笔数和主动买入成交量，并以可直接用于指标和回测的数据对象返回。

```python title="Pull a year of hourly spot and perpetual futures bars for BTCUSDT"
>>> kwargs = dict(start="2024-01-01", end="2025-01-01", timeframe="1h")
>>> spot = vbt.BinanceData.pull("BTCUSDT", **kwargs)
>>> perp = vbt.BinanceData.pull("BTCUSDT", klines_type="futures", **kwargs)  # (1)
>>> spot.features[5:]  # (2)
['Quote volume', 'Trade count', 'Taker base volume', 'Taker quote volume']

>>> def summarize(d):
...     return {
...         "volume (M BTC)": d.volume.sum() / 1e6,
...         "trades (M)": d.get("Trade count").sum() / 1e6,
...         "taker buys": d.get("Taker base volume").sum() / d.volume.sum(),
...     }

>>> pd.DataFrame({"spot": summarize(spot), "perpetual": summarize(perp)}).T.round(3)
           volume (M BTC)  trades (M)  taker buys
spot               12.931    1015.161       0.497
perpetual         100.355    1365.867       0.497

>>> basis_bps = (perp.close / spot.close - 1) * 10_000  # (3)
>>> basis_bps.describe().round(2)
count    8784.00
mean       -0.29
std         5.25
min       -20.76
25%        -4.44
50%        -2.76
75%         4.70
max        28.88
Name: Close, dtype: float64
```

1.  U 本位期货。不传入 `klines_type` 执行相同拉取时，返回现货 K 线。
2.  Binance 在常规开盘价、最高价、最低价、收盘价和成交量之外提供的字段。
3.  永续合约相对于现货的溢价，以基点计。

两个市场都返回了 2024 年全部 8,784 小时数据。永续合约成交量是现货的 7.8 倍，其小时收盘价与现货的差距始终在 29
个基点以内。两个市场中，主动买入量几乎都正好占全年成交量的一半。每小时占比可根据主动买入成交量和总成交量计算。

## 从 Binance K 线到策略研究 \[#from-binance-candles-to-strategy-research]

额外字段让您提出仅凭价格无法回答的问题。突破伴随更多成交笔数时，表现是否不同？更高的主动买入占比是否有助于过滤入场信号？策略在现货与永续合约上的表现如何？您可以将这些特征与指标一起计算，并通过[信号回测](/zh/features/backtesting/signal-backtesting/)测试。

上述示例使用对应的小时 K
线比较两个市场。使用同样方法，可以研究永续合约何时高于或低于现货，或比较多个币种的交易活跃度。价格和额外字段一起保存在数据对象中，因此选择标的或时段时无需重建数据集。处理下载数据的方法见[数据流水线](/zh/features/data/financial-data-pipelines/)。

## 现货与期货 \[#spot-and-futures]

`klines_type` 选择市场和价格序列：

| 数据     | `klines_type`                                          | 用途              |
| ------ | ------------------------------------------------------ | --------------- |
| 现货     | `"spot"`（默认）                                           | 币价、成交量和活跃度      |
| U 本位期货 | `"futures"`                                            | 合约价格及现货与期货比较    |
| 币本位期货  | `"futures_coin"`                                       | 研究以标的币种作为保证金的合约 |
| 期货标记价格 | `"futures_mark_price"` 或 `"futures_coin_mark_price"`   | 比较成交价与标记价格      |
| 期货指数价格 | `"futures_index_price"` 或 `"futures_coin_index_price"` | 比较合约与其参考指数      |

现货和 U 本位成交 K 线包括开盘、最高、最低、收盘和成交量，以及计价资产成交量、成交笔数、主动买入的基础资产和计价资产成交量。这些主动买入字段衡量主动吃单者发起的买入行为，而 OHLC K
线本身无法显示这些信息。

研究成交量时请选择成交 K 线。标记价格和指数 K 线提供参考价格，活跃度字段则为占位值，详见
[Binance 市场数据参考](https://developers.binance.com/en/docs/catalog/core-trading-derivatives-trading-usd-s-m-futures/api/rest-api/market-data)。

## 下载与更新历史数据 \[#downloading-and-updating-historical-data]

时间周期从一分钟到一个月，例如 `"1m"`、`"1h"` 或 `"1d"`；日期接受 `"2024-01-01"` 或 `"1 year ago"`
等字符串。请求起点早于标的首笔交易时，会从第一根可用 K 线开始，因此可以放心请求较长区间。结束日期不包含在结果内：示例在 2025 年 1 月 1 日之前结束，覆盖 2024 年完整日历年。

默认每批请求 1,000 根 K 线，批次之间暂停 0.5 秒。每批从上一批结束处开始，因此单个标的顺序下载：一年分钟 K 线约需 530 次请求和数分钟。通过
`execute_kwargs=dict(engine="threadpool")` 可以使用并行线程拉取多个标的，但总请求量必须遵守 Binance 的速率限制。

请将 `data.update()` 的结果赋值以保留最新数据。更新从最后一根已存 K 线开始，刷新该 K
线并添加更新的数据。如果拉取时设置了固定结束日期，更新时需提供更晚的结束日期。如何将大量历史保存在磁盘并定时更新，请参阅[数据存储与数据库](/zh/features/data/data-storage-and-databases/)。

## 查找交易标的 \[#finding-symbols]

`vbt.BinanceData.list_symbols` 列出现货标的，可用 glob 通配符或正则表达式筛选：

```python title="List Binance symbols that match a pattern"
>>> vbt.BinanceData.list_symbols("BTC*USDT")
['BTCDOWNUSDT', 'BTCSTUSDT', 'BTCUPUSDT', 'BTCUSDT']
```

一次拉取多个标的，会返回每个标的一列、对齐到共同索引的数据对象。

## 账户与地区 \[#accounts-and-regions]

该类使用通过 `pip install python-binance` 安装的 `python-binance` 客户端，而非无关的 `binance` 包。历史 K 线公开提供，无需 API
密钥。密钥和其他客户端选项传入 `client_config`，`client_config=dict(tld="us")` 可连接 Binance.US。如果已经使用
`python-binance`，可通过 `client` 传入现有客户端，以在多次拉取间复用配置。对于其他众多交易所，`vbt.CCXTData` 通过 CCXT
提供相同接口，如[市场数据源](/zh/features/data/market-data-sources/)页面所示。