跳至内容

永续合约连接器 v2.1

前提条件

在开始设置现货连接器之前,请确保您的系统上已安装 Hummingbot 源码版本。请按照 Hummingbot 安装指南 中提供的详细说明进行操作。

API 清单

名称 必需 类型 备注 路径 URL
获取活跃交易市场 是 公共 REST 获取活跃交易对列表的端点。示例 GET /markets
获取最新成交价格 False 公共 REST GET /markets
获取订单簿快照 False 公共 REST GET /markets/{market_name}/orderbook?depth={depth}
[TR] 最小名义金额 条件性 公共 REST 获取交易规则的端点。示例 GET /markets
[TR] 最小订单数量 条件性 公共 REST 获取交易规则的端点。示例 GET /markets
[TR] 最小价格 条件性 公共 REST 获取交易规则的端点。示例 GET /markets
[TR] 订单增量 条件性 公共 REST 获取交易规则的端点。示例 GET /markets
PING 端点 是 公共 REST 用于低信息量的端点,例如 ping。示例 GET /
获取账户余额 是 私有 REST 获取当前账户余额。 示例 GET /wallet/balances
通过客户端订单 ID 获取订单状态 条件性 私有 REST GET /orders/by_client_id/{client_order_id}
通过 exchange_order_id 获取订单状态 条件性 私有 REST GET /orders/{order_id}
通过订单 ID 获取交易历史 条件性 私有 REST GET /fills
按时间戳获取交易历史 条件性 私有 REST GET /fills
获取未成交订单 是 私有 REST 获取活跃订单。 示例 GET /orders
创建订单 是 私有 REST 创建新订单。 示例 POST /orders
使用客户端订单 ID 创建订单 条件性 私有 REST 创建新订单。 示例 POST /orders
通过 exchange_order_id 取消订单 是 私有 REST DELETE /orders
通过客户端订单 ID 取消订单 条件性 私有 REST DELETE /orders
订单簿频道(最小深度 100) 是 公共 Websocket 公共订单频道。 示例 orderbook
订单簿差异频道 条件性 公共 Websocket 公共订单频道。 示例 orderbook
用户交易频道(订单状态、成交记录、费用) 是 私有 Websocket 私有订单更新。 示例 fills
用户订单频道(订单状态、成交记录、费用) 私有 Websocket 订单
用户余额频道(总额和可用额) False 私有 Websocket 私人余额事件。示例
身份验证 是 其他 网页助手的身份验证逻辑。示例
速率限制 是 其他 速率限制文档。示例
服务器时间 条件性 公共 REST
资金费用支付 是 公共 REST 资金费用支付信息 GET /funding_payments
获取当前持仓 是 私有 REST 获取当前仓位 GET /positions

构建流程

常量

向常量文件中添加以下变量

  • 默认域名:检查是否需要添加多个域名,该常量将用于 web_utils 中生成路径 URL。
  • REST_URLS:可以像 ByBit 连接器那样是字典,也可以像 Binance 连接器那样是 f-string,DEFAULT DOMAIN 变量将用于选择正确的 URL。
  • SERVER_TIME_PATH_URL:检查交易所是否要求您的 时间戳 与服务器时间同步。

网络工具

  • connector_name_web_utils.py 文件
    • 复制 Bybit 永续合约连接器的 web_utils 文件。
    • 将 Bybit 永续合约中的 connector_name 首字母替换为大写。
    • 将 Bybit 永续合约中的 connector_name 替换掉。
    • 检查是否需要线性永续合约,或移除该逻辑。
    • 如果发现某种模式,可以编写函数从 REST 响应中提取结果或成功状态。
    • 你也可以编写函数来从 WebSocket 频道中提取主题和负载数据。
    • 编写创建 REST URL 的函数,检查是否需要公共和私有 URL,或仅需其中之一。
    • 如果需要时间同步:
      • 确认你拥有 build_api_factory_without_time_synchronizer_pre_processor 函数。
      • 检查 get_current_server_time 函数是否需要修改(可能需要在响应中查找服务器时间)。
      • 在 build_api_factory 中将时间同步器作为 rest_pre_processor 添加。
    • 如果不需要时间同步:
      • 删除与时间同步相关的文件,并编写不包含时间同步功能的 build_api_factory 函数。

工具模块

  • 在 connector_name_utils.py 文件中编码
    • 复制 Bybit 永续合约连接器的 utils 文件。
    • 将 Bybit 替换为 connector_name,首字母大写。
    • 将 bybit_perpetual 替换为 connector_name。
    • 使用适当的值替换 DEFAULT_FEES。
    • 检查是否需要连接其他域名,否则删除。
    • 检查是否需要线性交易,或将其删除。

订单簿数据源

  • connector_name_api_order_book_data_source.py

    • 复制 Bybit 永续合约连接器的订单簿数据源文件。
    • 将 connector_name 中的 bybit 替换为首字母大写的形式。
    • 将 connector_name 中的 bybitl 替换掉。
    • 使用适当的值替换 HEARTBEAT_TIME_INTERVAL。
  • test_connector_name_api_order_book_data_source.py

    • 复制 Bybit 永续合约订单簿数据源测试文件。
    • 将 connector_name 中的 bybit 替换为首字母大写的形式。
    • 将 connector_name 中的 bybit 替换掉。

    现在我们将开始以测试驱动开发(TDD)的方式实现订单簿数据源的功能。

  • 方法开发

    • REST

      • orderbook

        • test_get_new_order_book_successful
        • _order_book_snapshot
        • _request_order_book_snapshot
        • test_get_new_order_book_raises_exception
      • funding_info

        • test_get_funding_info
        • get_funding_info
    • WEBSOCKET

      • listen_for_subscriptions

        • test_listen_for_subscriptions_subscribes_to_trades_and_order_diffs_and_funding_info
        • listen_for_subscriptions (位于父类中)
        • _connected_websocket_assistant
        • _subscribe_channels
        • _process_websocket_messages
        • _channel_originating_message
        • test_listen_for_subscriptions_raises_cancel_exception
        • test_listen_for_subscriptions_logs_exception_details
        • test_subscribe_channels_raises_cancel_exception
        • test_subscribe_channels_raises_exception_and_logs_error
      • 监听交易

        • test_listen_for_trades_successful
        • _parse_trade_message
        • test_listen_for_trades_cancelled_when_listening
        • test_listen_for_trades_logs_exception
      • 监听订单簿差异

        • test_listen_for_order_book_diffs_successful
        • listen_for_order_book_diffs
        • _parse_order_book_diff_message
        • test_listen_for_order_book_diffs_cancelled
        • test_listen_for_order_book_diffs_logs_exception
      • 监听订单簿快照

        • test_listen_for_order_book_snapshots_cancelled_when_fetching_snapshot
        • listen_for_order_book_snapshots
        • _parse_order_book_snapshot_message
        • test_listen_for_order_book_snapshots_log_exception
        • test_listen_for_order_book_snapshots_successful
      • 监听资金费率信息

        • test_listen_for_funding_info_cancelled_when_listening
        • _parse_funding_info_message
        • test_listen_for_funding_info_logs_exception
        • test_listen_for_funding_info_successful

认证

  • connector_name_auth.py
    • 复制 Bybit 永续合约连接器的认证文件。
    • 将 connector_name 中的 Bybit 替换为首字母大写的形式。
  • test_connector_name_auth.py

    • 复制 Bybit 永续合约认证文件的测试代码。
    • 将 connector_name 中的 Bybit 永续合约替换为首字母大写的形式。
    • 将 connector_name 替换为 Bybit 永续合约。
  • 方法开发

    • REST

      • rest_authenticate
        • 测试 rest_authenticate
        • rest_authenticate
        • add_auth_to_params
        • header_for_authentication
        • _generate_signature
    • WEBSOCKET

      • ws_authenticate

用户流数据源

  • connector_name_api_user_stream_data_source.py

    • 复制 Bybit 永续合约连接器的用户流数据源文件。
    • 将 connector_name 中的 bybit 替换为首字母大写的形式。
    • 将 connector_name 中的 bybit 替换掉。
    • 使用适当的值替换 HEARTBEAT_TIME_INTERVAL。
    • 检查是否需要 LISTEN_KEY_KEEP_ALIVE_INTERVAL。
  • test_connector_name_api_user_stream_data_source.py

    • 复制 Binance 用户流数据源文件的测试。
    • 将 connector_name 中的 Binance 替换为首字母大写的形式。
    • 将 connector_name 替换为 binance。

    现在我们将开始以测试驱动开发(TDD)的方式实现用户流数据源的功能。

  • 方法开发

    • WEBSOCKET

      如果需要 Listen Key:

      • get_listen_key

        • 测试 get_listen_key 时记录异常
        • _get_listen_key
        • 测试 get_listen_key 成功
        • 测试 ping_listen_key 时记录异常
        • _ping_listen_key
        • 测试 ping_listen_key 成功
        • 测试 manage_listen_key_task_loop 心跳失败
        • _manage_listen_key_task_loop
        • 测试 manage_listen_key_task_loop 心跳成功
      • listen_for_user_stream

        • test_listen_for_user_stream_get_listen_key_successful_with_user_update_event
        • listen_for_user_stream (位于父类中)
        • _connected_websocket_assistant
        • _subscribe_channels
        • _get_ws_assistant
        • _on_user_stream_interruption
        • test_listen_for_user_stream_does_not_queue_empty_payload
        • test_listen_for_user_stream_connection_failed
        • test_listen_for_user_stream_iter_message_throws_exception

交易所

  • connector_name_exchange.py

    • 复制 Bybit 永续合约连接器的衍生文件。
    • 将 connector_name 中的 bybit 替换为首字母大写的形式。
    • 将 connector_name 中的 bybit 替换掉。
  • test_connector_name_exchange.py

    • 复制 Bybit 衍生文件的测试代码。
    • 将 connector_name 中的 bybit 替换为首字母大写的形式。
    • 将 connector_name 中的 bybit 替换掉。
  • 方法开发

    许多测试已经存在于通用测试类中!但你需要实现一些方法以使其正常运行。

    • 通用测试类所需的方法

      • all_symbols_request_mock_response
      • latest_prices_request_mock_response
      • all_symbols_including_invalid_pair_mock_response
      • network_status_request_successful_mock_response
      • trading_rules_request_mock_response
      • trading_rules_request_erroneous_mock_response
      • order_creation_request_successful_mock_response
      • balance_request_mock_response_for_base_and_quote
      • balance_request_mock_response_only_base
      • balance_event_websocket_update
      • expected_latest_price
      • expected_supported_order_types
      • expected_trading_rule
      • 预期的错误交易规则日志错误
      • 预期的交易所订单 ID
      • 服务器是否同步执行取消请求
      • 状态更新中是否包含订单成交的 HTTP 更新
      • 是否在 WebSocket 订单事件处理期间执行订单成交的 HTTP 更新
      • 预期的部分成交价格
      • 预期的部分成交数量
      • 预期的成交手续费
      • 预期的成交交易 ID
      • 代币的交易所符号
      • 创建交易所实例
      • 验证认证凭据是否存在
      • 验证订单创建请求
      • 验证订单取消请求
      • 验证订单状态请求
      • 验证交易记录请求
      • 配置成功的取消响应
      • 配置错误的取消响应
      • 配置一个成功一个失败的全部取消响应
      • 配置完全成交订单的状态响应
      • 配置已取消订单的状态响应
      • 配置错误的 HTTP 成交交易响应
      • 配置未完成订单的状态响应
      • 配置 HTTP 错误订单状态响应
      • 配置部分成交订单的状态响应
      • 配置部分成交交易响应
      • 配置完全成交交易响应
      • 新订单的订单事件 WebSocket 更新
      • 已取消订单的订单事件 WebSocket 更新
      • 完全成交订单事件的 WebSocket 更新
      • 完全成交交易事件的 WebSocket 更新
      • 空的资金费用模拟响应
      • 预期支持的持仓模式
      • 资金费率信息模拟响应
      • 资金费率信息 URL
      • 资金费用支付 URL
      • 资金费用支付模拟响应
      • 配置设置杠杆失败
      • 配置设置杠杆成功
      • 完全成交持仓事件的 WebSocket 更新
      • 资金费率信息事件的 WebSocket 更新
      • 配置设置持仓模式成功
      • 配置设置持仓模式失败
    • 需实现的 ExchangePyBase 方法

      • 认证器
      • 名称
      • 限速规则
      • 域名
      • 客户端订单 ID 最大长度
      • 客户端订单 ID 前缀
      • 交易规则请求路径
      • 交易对请求路径
      • check_network_request_path
      • 交易对
      • 是否取消请求在交易所同步
      • 是否需要交易
      • 支持的订单类型
      • _is_request_exception_related_to_time_synchronizer
      • _create_web_assistants_factory
      • _create_order_book_data_source
      • _create_user_stream_data_source
      • _get_fee
      • _place_order
      • _place_cancel
      • _format_trading_rules
      • _status_polling_loop_fetch_updates
      • _update_trading_fees
      • _user_stream_event_listener
      • _all_trade_updates_for_order
      • _request_order_status
      • _update_balances
      • _initialize_trading_pair_symbols_from_exchange_info
      • _get_last_traded_price
    • 需实现的 PerpetualDerivativePyBase 方法

      • 资金费用轮询间隔
      • 支持的持仓模式
      • 获取买入抵押代币
      • 获取卖出抵押代币
      • _create_order_book_data_source
      • _update_positions
      • _set_trading_pair_leverage
      • _fetch_last_fee_payment
    • 更新时间同步器

      • 测试更新时间同步器成功
      • _update_time_synchronizer
      • 测试更新时间同步器失败时被记录
      • 测试更新时间同步器抛出取消错误
      • 测试时间同步器相关请求错误检测
    • 更新订单成交记录

      • 测试从交易中更新订单成交记录会触发已成交事件
      • _update_order_fills_from_trades
      • 测试更新订单成交记录的请求参数
      • 测试从交易中更新订单成交记录时,重复的成交仅触发一次事件
    • 更新订单状态

      • 测试更新订单状态失败时的情况
      • _update_order_status
    • _user_stream_event_listener

      • 测试用户流更新订单失败事件
      • _user_stream_event_listener
    • 仓位模式

      • 测试设置持仓模式失败
      • 测试设置持仓模式成功
    • funding_info

      • 测试监听资金费率更新初始化资金信息
      • 测试监听资金费率更新并更新资金信息
      • 测试初始化资金信息
      • 测试资金费率轮询循环成功
      • 测试资金费率轮询循环抛出异常
  • 将 connector_name_api_key 和 connector_name_api_secret 添加到 conf_global_TEMPLATE.yml