交易所 API 要求

注意

以下信息适用于开发直接集成到 Hummingbot 客户端的 spot 和 perp 连接器的开发者。有关使用 Gateway 开发 gateway 连接器的信息，请参阅构建 Gateway 连接器。

API 要求¶

具有 REST API 的交易所必须提供以下接口：

获取交易规则的端点。 (示例)
检查服务器状态的端点（通常任何返回少量信息的端点都可以用于此目的，但 ping 或时间端点是最理想的）。 (示例)
获取当前挂单的端点。 (示例)
创建新订单的端点。 (示例)
获取当前账户余额的端点。 (示例)
每个端点应用的速率限制以及每个 IP/连接的全局限制的文档说明。 (示例)

如果 REST API 能提供以下内容会很有帮助，但即使没有这些也可以构建连接器：

获取活跃交易对列表的端点（有时称为“代币信息”）。 (示例)

具有 WebSocket API 的交易所必须提供：

公开订单频道 (示例)
公开成交频道 (示例)
私有订单更新频道 (示例)
私有成交事件频道 (示例)
每个订阅所应用的速率限制以及每个 IP/连接的全局限制的文档说明

如果 WebSocket API 还能提供以下内容会很有帮助，但即使没有这些也可以构建连接器：

私有余额事件频道（如果不存在，则需要配置连接器以根据其活动估算余额） (示例)
成交事件中包含每笔交易收取费用的详细信息（如果不存在，连接器将不得不通过估算费用来运行）

永续合约连接器的额外要求¶

用于查询持仓的 REST API 接口 (示例)
用于配置杠杆的 REST API 接口 (示例)

组件¶

下面，我们将描述创建新连接器所需实现的组件。某些组件可以并行实现，但其他组件存在依赖关系。

身份验证¶

提供 Web 助手逻辑的类，以正确配置向交易所（私有端点）发送的身份验证请求。它应为 AuthBase 的子类

示例: https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/exchange/binance/binance_auth.py

依赖项: 无

工具模块¶

工具模块通常用于定义在连接器多个组件中使用的函数。如果连接器在创建请求时不需要特殊行为，或无需特殊逻辑生成订单 ID，则无需添加函数。

需要在此模块中定义连接器的配置，包括： - 默认手续费 - 建立连接所需的参数（例如 API 密钥和 API 密钥密文）。

必须为连接器支持的每个域指定相应的配置（所有连接器只要正确配置，均可支持多个域）

示例: https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/exchange/binance/binance_utils.py

依赖项: 无

订单簿¶

继承自 OrderBook 的子类，用于根据数据源接收到的事件定义创建快照消息、差异消息和交易消息的专用方法

示例: https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/exchange/binance/binance_order_book.py

依赖项: 无

订单簿数据源¶

继承自 OrderBookTrackerDataSource 的子类。包含通过 WebSocket 接收所有公共频道更新的所有逻辑。该类应包括： - 提供一个或多个交易对在交易所最新价格的逻辑 - 返回所有支持的交易对的逻辑（例如过滤掉交易所中可能已禁用的交易对） - 将交易对从交易所表示法转换为客户端表示法的功能，以及反向转换 - 获取特定交易对当前订单簿完整副本的方法 - 订阅所需公共频道的逻辑，并处理所有接收到的事件。所需频道包括：订单簿差异和公开交易事件。还需要一种定期执行订单簿全量更新（快照）的方法。

必须为连接器创建一个追踪器类（OrderBookTracker 的子类），以启动接收事件并进行更新的后台进程。

示例: - https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/exchange/binance/binance_api_order_book_data_source.py - https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/exchange/binance/binance_order_book_tracker.py

依赖项: 订单簿（用于生成差异消息、快照消息和交易消息）

用户流数据源¶

是 UserStreamTrackerDataSource 的子类

该类应包含：- 订阅私有 WebSocket 频道以接收订单更新、成交更新和余额更新的逻辑；- 处理每种事件类型的逻辑

必须为连接器创建一个追踪器类（UserStreamTracker 的子类），以启动后台进程来接收事件并进行更新。

示例：

依赖项：

订单簿数据源（仅用于将交易对转换为交易所的表示格式）
身份验证组件

连接器¶

继承自 ExchangeBase（适用于交易所连接器）或 ConnectorBase（适用于Gateway 连接器）。

它应包含：

启动和停止正常运行所需的所有连接和订阅的逻辑。
判断连接器是否已准备就绪可运行的方法（所有连接均已建立），并定期检查其状态
订单生命周期的功能：创建与取消。为了正确跟踪订单并处理，应使用 ClientOrderTracker 实例
向服务器发送 REST 请求（使用 WebAssistant）并正确处理错误结果的方法
定期更新交易规则的方法
定期通过 REST API 更新余额的逻辑（作为通过 WebSocket 接收更新的备用机制）
定期通过 REST API 检查订单更新的逻辑（作为通过 WebSocket 接收更新的备用机制）
正确处理通过用户流收到的私有频道事件的功能

示例：https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/exchange/binance/binance_exchange.py

依赖项：

订单簿数据源
用户流数据源

永续合约连接器的额外要求¶

对于永续合约交易所连接器，连接器组件还应继承自 PerpetualTrading，并需包含以下功能：

从交易所获取当前杠杆并在交易所设置杠杆的逻辑
提供支持的持仓模式，并在交易所中更改（如果交易所允许）
获取当前资金费率信息的方法以及定期更新的逻辑
保持持仓状态更新的逻辑

示例：https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/derivative/binance_perpetual/binance_perpetual_derivative.py

单元测试¶

预期上述所有组件都有单元测试来验证所有方法。这独立于 QA 测试所做的任何验证。

所有连接器的单元测试都不应依赖与交易所的实际连接来进行验证。相反，与交易所的交互应始终被模拟或仿真。可以使用 aioresponses 库处理所有 REST 请求，使用 NetworkMockingAssistant 类处理 WebSocket 交互。

可以在 Binance 和 Binance 永续合约连接器的单元测试中找到其使用示例。

Binance 连接器测试： https://github.com/hummingbot/hummingbot/tree/master/test/hummingbot/connector/exchange/binance

Binance 永续合约连接器测试： https://github.com/hummingbot/hummingbot/tree/master/test/hummingbot/connector/derivative

特殊注意事项¶

当没有可用的 websocket 余额事件时的连接器配置¶

当交易所未提供用于余额更新的 websocket 端点时，必须将连接器配置为基于连接器活动来估算余额。

将 _real_time_balance_update 变量设置为 False
使用 REST API 定期更新余额的方法还应通过以下代码行更新飞行中的订单快照：

self._in_flight_orders_snapshot = {k: copy.copy(v) for k, v in self._in_flight_orders.items()}
self._in_flight_orders_snapshot_timestamp = self.current_timestamp

例如，请参考 Bybit 连接器：https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/derivative/bybit_perpetual/bybit_perpetual_derivative.py