无噪 logo
本文档翻译于 2025-10-20
  • 文档更新翻译历史
  • 2025-10-20 常规更新
Hummingbot
FTX 中国债权 我的
跳至内容

连接器架构

注意

以下信息适用于开发直接集成到 Hummingbot 客户端的现货和永续合约连接器的开发者。有关使用Gateway开发网关连接器的信息，请参阅构建网关连接器。

以下是连接器的高层设计：

Connector Architecture Diagram

请注意，对于衍生品（perp）连接器，我们采用多重继承方式继承自ExchangeBase和PerpetualTrading。

组件概述

Connector Architecture Diagram

每个连接器由以下组件组成。下文详细描述了每个组件及其对应文件的任务。

交易所/衍生品.py

文件： *_exchange/derivative.py — 必需

连接器模块围绕一个Exchange/Derivative类展开，该类最终继承自ConnectorBase。Exchange/Derivative类包含一个OrderBookTracker和一个UserStreamTracker，负责维护订单簿和用户账户信息。

Exchange/Derivative实例还包含一个ClientOrderTracker，用于跟踪连接器的InFlightOrders（即由 Hummingbot 提交且当前在订单簿上的订单）。通常，拥有一个特定于交易所的Auth类也很有帮助，该类生成访问受限 REST 端点和 WebSocket 频道所需的身份验证参数/头部，例如用于下单和监听订单更新。

特别是Derivative类，继承了专用于永续合约市场的功能。更多信息请参见PerpetualTrading类。

ConnectorAuth.py

文件： *_auth.py — 可选

此类为受限 REST 端点生成适当的身份验证头部，供Exchange/Derivative和UserStreamTrackerDataSource类使用。通常这意味着根据交易所 API 文档的要求构造适当的 HTTP 头部和身份验证载荷。

一些常见的参数包括：

  • HTTP 请求类型
  • 端点 URL
  • 必须传递给交易所的参数（例如 API 密钥、密码、请求体）

根据具体交易所的不同，身份验证可能需要不同的信息。通常情况下，Auth 类会：

  • 生成时间戳/随机数。基于时间、访问方法、端点、提供的参数以及用户的私钥生成签名。
  • 将公钥、时间戳、提供的参数和签名编译成字典，通过 http 或 ws 请求发送。

注意

此模块通常仅适用于中心化交易所。去中心化交易所（DEX）的身份验证一般由对应钱包处理。

订单簿追踪器

文件： *_order_book_tracker.py — 必需

每个 交易所/衍生品 类都包含一个 OrderBookTracker，用于维护一个或多个交易对的实时订单簿，并负责将订单簿快照和增量消息应用到相应的 OrderBook 上。

  • 一个 OrderBookTracker 包含一个字典，其中每个交易对都有对应的 OrderBook 实例。
  • APIOrderBookTrackerDataSource 类包含用于从交易所获取订单簿数据的 API 请求或 WebSocket 数据流。
  • OrderBook 类包含将交易所返回的原始订单簿快照/增量消息转换为可用的活跃买盘和卖盘字典的方法。

用户数据流追踪器

文件： *_user_stream_tracker.py — 可选

每个 交易所/衍生品 类包含一个 UserStreamTracker，用于维护用户账户、订单和持仓的当前状态。

  • APIUserStreamTrackerDataSource 类包含用于从交易所获取用户余额和订单数据的 API 请求或 WebSocket 数据流。
  • 从 交易所/衍生品 类传递的 Auth 包含构建适当身份验证请求的方法，用于 REST API 调用或 WebSocket 频道订阅请求。

订单簿数据源

文件： *_order_book_data_source.py — 必需

OrderBookTrackerDataSource 类负责订单簿数据的获取。它仅负责收集、解析并将数据流排队，供 OrderBookTracker 处理。通常这意味着从交易所的 API/WebSocket 服务器拉取数据。对于永续合约连接器，OrderBookTrackerDataSource 还需负责维护活跃市场的资金费率信息。

有必要跟踪从交易所 API 服务器接收到的每条消息的时间戳/随机数，以保持订单簿的一致性和最新性。根据交易所的响应情况，我们可以通过以下方式维护订单簿：

  1. 存在时间戳/随机数
  2. 在这种理想情况下，只有当接收到的消息的时间戳/随机数大于或+1于订单簿中的 _last_diff_uid 时，才会将增量消息应用到订单簿上。
  3. 缺少时间戳/随机数
  4. 在这种情况下，我们必须为从交易所收到的每条消息分配一个时间戳，并且只有在快照消息之后收到该消息且其时间戳大于_last_diff_uid时，才按顺序应用增量消息。

注意

必须确保所维护的订单簿反映所有变更，并与交易所的订单簿保持一致。作为安全措施或备用方案，当 Hummingbot 无法充分维护订单簿时，定期执行订单簿快照请求有助于纠正任何遗漏的增量数据。

UserStreamTrackerDataSource

文件： *_user_stream_data_source.py — 可选

UserStreamTrackerDataSource 类负责用户数据的获取。它仅收集、解析并将数据流排队，供 UserStreamTracker 处理。

与 OrderBookTrackerDataSource 不同，UserStreamTrackerDataSource 仅获取有关用户账户余额和订单的数据。

InFlightOrder

文件： /hummingbot/core/data_type/in_flight_order.py

存储与订单当前状态相关的所有详细信息。

保持用户提交的所有活跃订单状态的一致性和准确性至关重要。这能确保策略获得正确的信息，并能够相应地执行任务。

ClientOrderTracker

文件： /hummingbot/connector/client_order_tracker.py

ClientOrderTracker 实例通过调用连接器的 trigger_event 方法来持有和管理 InFlightOrder 订单。

为连接器提供更新进行中订单及处理订单错误的工具。

费用核算

BudgetChecker 使用 TradeFeeSchema 中的信息生成特定的 TradeFeeBase 实例，并将其应用于 OrderCandidate，以评估该订单对账户余额的影响。

TradeFee

TradeFee 对象包含估算订单对账户余额影响时所需的相关费用信息。

示例：TradeFee 

from hummingbot.client.settings import AllConnectorSettings

trade_fee_schema = AllConnectorSettings.get_connector_settings()[exchange].trade_fee_schema

percent = trade_fee_schema.maker_percent_fee_decimal if is_maker else trade_fee_schema.taker_percent_fee_decimal
fixed_fees = trade_fee_schema.maker_fixed_fees if is_maker else trade_fee_schema.taker_fixed_fees

trade_fee = AddedToCostTradeFee(percent, trade_fee_schema.percent_fee_token, fixed_fees)

TradeFeeSchema

包含构建 TradeFee 对象所需的必要信息。

针对挂单方（maker）和吃单方（taker），指定百分比费用和固定费用，以及支付费用所用的代币。

交易所必须在其各自的 [exchange]_utils.py 文件中定义默认的费用结构：

DEFAULT_FEES = TradeFeeSchema(
    maker_percent_fee_decimal=Decimal("0.001"),
    taker_percent_fee_decimal=Decimal("0.001")
)

  • percent_fee_token: str
  • maker_percent_fee_decimal: Decimal
  • taker_percent_fee_decimal: Decimal
  • buy_percent_fee_deducted_from_returns: bool
  • maker_fixed_fees: List
  • taker_fixed_fees: List

示例：TradeFeeSchema 

trade_fee_schema = TradeFeeSchema(
    maker_percent_fee_decimal=Decimal("1.0"),
    taker_percent_fee_decimal=Decimal("2.3")
)

TradeFeeBase

TradeFeeBase 类的一个具体实例定义了应用于订单的费用——其类型、金额和资产。

  • fee_amount_in_quote()：以百分比费用和固定费用的组合方式，计算以报价资产为单位的总费用
  • get_fee_impact_on_order_cost()：返回考虑费用后特定开仓OrderCandidate的订单成本
  • get_fee_impact_on_order_returns()：返回考虑费用后特定平仓OrderCandidate的订单收益

AddedToCostTradeFee

继承自 TradeFeeBase，并实现了 get_fee_impact_on_order_cost() 和 get_fee_impact_on_order_returns() 方法。

此类的费用会叠加在买入订单的成本之上（例如，以 9 USDT 的价格购买 10 COINX，且手续费为 1%，意味着用户账户将扣除 90.9 USDT 并增加 10 COINX —— 这是大多数交易所对费用的处理方式）。

DeductedFromReturnsTradeFee

继承自 TradeFeeBase，并实现了 get_fee_impact_on_order_cost() 和 get_fee_impact_on_order_returns() 方法。

此类的费用从买入订单的收益中扣除（例如，以 9 USDT 的价格购买 10 COINX，且手续费为 1%，意味着用户账户将扣除 90 USDT 并增加 9.9 COINX —— 这是币安交易所的费用处理方式）。