跳转至内容

连接器架构

注意

以下信息适用于构建直接集成到 Hummingbot 客户端的 spot 和 perpetual 连接器的开发人员。有关使用 Gateway 开发 gateway 连接器的信息，请参见 Building Gateway Connectors。

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

Connector Architecture Diagram

请注意，对于衍生品 (perp) 连接器，我们有多重继承到 ExchangeBase 和 PerpetualTrading。

组件概述

Connector Architecture Diagram

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

Exchange/Derivative.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 — 可选

此类为 Exchange/Derivative 和 UserStreamTrackerDataSource 类使用的受限 REST 端点生成适当的身份验证标头。通常，这将意味着构建适当的 HTTP 标头和身份验证载荷（如交易所 API 文档所指定的）

一些参数通常包括：

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

根据特定交易所，身份验证可能需要不同的信息。通常，Auth 类将：

  • 生成时间戳/nonce。基于时间、访问方法、端点、提供的参数和用户私钥生成签名。
  • 将公钥、时间戳、提供的参数和签名编译成一个字典，通过 http 或 ws 请求传递。

注意

此模块通常仅对中心化交易所必需。通常，DEX 的身份验证由相应钱包处理。

OrderBookTracker

文件： *_order_book_tracker.py — 必需

每个 Exchange/Derivative 类包含一个 OrderBookTracker，用于维护一个或多个交易对的实时订单簿，并负责将订单簿快照和差异消息应用到相应的 OrderBook。

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

UserStreamTracker

文件： *_user_stream_tracker.py — 可选

每个Exchange/Derivative类都包含一个UserStreamTracker，用于维护用户账户、订单和头寸的当前状态。

  • APIUserStreamTrackerDataSource类包含 API 请求或 WebSocket 数据流，用于维护来自交易所的用户余额和订单数据。
  • 从Exchange/Derivative类传递的Auth包含为 REST API 调用或 WebSocket 频道订阅请求构建适当身份验证请求的方法。

OrderBookTrackerDataSource

文件： *_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 方法来持有和管理 InFlightOrders。

为连接器提供更新在途订单和处理订单错误的工具。

费用计算

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 对象所需的必要信息。

对于做市商和吃单者，指定百分比费用和固定费用，以及支付费用的代币。

交易所必须在各自的 [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——这是币安的费用处理方式）。