NautilusTrader Bybit 适配器 API 参考与实战指南从配置类到实时行情与执行【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader本篇技术指南围绕 NautilusTrader 开源交易引擎中 Bybit 交易所适配器nautilus_trader.adapters.bybit模块的完整公开 API 展开覆盖数据客户端与执行客户端的配置类、工厂类、底层 HTTP 客户端、核心枚举以及订单参数体系。读完本文你将掌握如何在 Python 中配置BybitDataClientConfig/BybitExecutionClientConfig搭建实盘交易节点理解 Bybit v5 API 与 NautilusTrader 事件驱动架构之间的映射关系并能熟练使用现货保证金、期权、原生 TP/SL、BBO 与自成交预防等高级订单能力。模块总览一个适配器多层抽象Bybit 适配器采用 Rust 实现、通过 PyO3 暴露给 Python是 NautilusTrader 中同构公开配置、工厂与数据类型的典型代表。Python 侧入口位于 python/nautilus_trader/adapters/bybit/init.py其公开符号直接来自nautilus_trader._libnautilus.bybit扩展模块并经由_fixup模块完成命名空间修复。模块公开的顶层组件按职责可划分为四层层次组件职责标识符BYBIT、BYBIT_CLIENT_ID、BYBIT_VENUE交易所名称、客户端 ID 与交易场所标识配置BybitDataClientConfig、BybitExecutionClientConfig数据/执行客户端的声明式配置工厂BybitDataClientFactory、BybitExecutionClientFactory供LiveNode.builder(...)装配客户端底层连接BybitHttpClient、BybitRawHttpClient面向 v5 REST 的 HTTP 通信与原始请求封装数据客户端BybitDataClient由数据工厂构建负责行情数据流管理执行客户端BybitExecutionClient由执行工厂构建是账户管理与下单网关。对绝大多数用户而言只需要定义配置并交给工厂无需直接操作底层组件。核心标识符与常量from nautilus_trader.adapters.bybit import BYBIT, BYBIT_CLIENT_ID, BYBIT_VENUEBYBIT: str交易所字符串名称用于InstrumentId.from_str(BTCUSDT-LINEAR.BYBIT)之类的符号解析BYBIT_CLIENT_ID: model.ClientId客户端标识用于消息总线路由BYBIT_VENUE: model.Venue交易场所标识用于账户、订单与成交的归属判定。在 examples/live/bybit/exec_tester.py 中可以看到它们的组合用法INSTRUMENT_ID InstrumentId.from_str(fETHUSDT-LINEAR.{BYBIT})、ACCOUNT_ID AccountId.from_str(BYBIT-001)。配置类详解两个配置类均由 Rust 侧 crates/adapters/bybit/src/python/config.rs 的#[pymethods]绑定暴露所有未显式传入的参数都会回落到 Rust 结构体的Default实现因此两个配置类都可以零参数构造此时按默认值连接 Bybit 主网。BybitDataClientConfig数据客户端配置负责行情订阅、合约目录加载与 WebSocket 心跳等参数参数默认值说明product_types[LINEAR]要启用的BybitProductType序列决定连接后加载哪些合约目录environmentMAINNETBybitEnvironment枚举MAINNET/DEMO/TESTNETapi_key/api_secretNoneAPI 凭证省略时从对应环境变量加载base_url_httpNoneREST 基础 URL 覆盖项默认由 environment 解析base_url_ws_public/base_url_ws_privateNone公开/私有 WebSocket URL 覆盖项proxy_urlNoneHTTP 与 WebSocket 传输的可选代理http_timeout_secs60REST 请求超时秒max_retries3REST 请求最大重试次数retry_delay_initial_ms1,000重试初始延迟毫秒retry_delay_max_ms10,000重试最大延迟毫秒heartbeat_interval_secs20WebSocket 心跳间隔秒recv_window_ms5,000签名 REST 请求的接收窗口毫秒update_instruments_interval_mins60合约目录刷新间隔分钟instrument_status_poll_secs60合约与状态轮询间隔秒0表示禁用轮询transport_backendSockudoWebSocket 传输后端network.TransportBackendBybitExecutionClientConfig执行客户端配置除共享参数外还包含账户与订单行为相关选项参数默认值说明base_url_ws_tradeNoneTrade WebSocket 基础 URL 覆盖项主网批量下单通道auth_timeout_secsNoneWebSocket 认证超时秒account_idNone与该客户端关联的AccountIduse_spot_position_reportsFalse将现货钱包余额作为持仓上报用于按作用域查询批量报表不包含现货无交易对归属auto_repay_spot_borrowsFalse现货 BUY 订单全部成交后自动归还追踪到的现货保证金借款margin_modeNone连接时应用到账户的统一保证金模式BybitMarginModesmp_typeNone每次下单都携带的自成交预防值None/CancelMaker/CancelTaker/CancelBoth不合法值会在构造时被拒绝从源码看smp_type的解析在 Python 绑定构造时即通过parse_smp_type完成见 crates/adapters/bybit/src/python/config.rs非法值会直接抛出ValueError而非延迟到下单阶段。凭证与环境变量凭证有两种提供方式直接传api_key/api_secret或使用环境变量官方推荐后者主网BYBIT_API_KEY、BYBIT_API_SECRET演示环境BYBIT_DEMO_API_KEY、BYBIT_DEMO_API_SECRET测试网BYBIT_TESTNET_API_KEY、BYBIT_TESTNET_API_SECRET节点启动时会立即校验凭证有效性及交易权限。典型执行客户端配置如下from nautilus_trader.adapters.bybit import BybitExecutionClientConfig config BybitExecutionClientConfig( api_keyYOUR_API_KEY, api_secretYOUR_API_SECRET, environmentBybitEnvironment.MAINNET, )核心枚举API 领域的类型安全映射枚举全部定义于 crates/adapters/bybit/src/common/enums.rs通过pyo3::pyclass绑定为 Python 枚举并支持from_str与整数构造。BybitEnvironment 与 BybitProductTypeBybitEnvironment提供三个交易环境对应不同的 API 端点枚举值场景解析出的端点以 TESTNET 为例MAINNET真实资金生产交易默认https://api.bybit.com等主网端点DEMO主网基础设施上的模拟资金演练私有流wss://stream-demo.bybit.com但公开行情仍走主网公开流TESTNET独立测试网络RESThttps://api-testnet.bybit.com公开 WSwss://stream-testnet.bybit.com/v5/public/{spot\|linear\|inverse\|option}私有 WSwss://stream-testnet.bybit.com/v5/privateTrade WSwss://stream-testnet.bybit.com/v5/tradeBybitProductType对应 v5 API 的category概念取值SPOT、LINEAR、INVERSE、OPTION。数据与执行客户端连接时会为所有配置的product_types加载合约目录默认仅LINEAR因此订阅或下单涉及其他品类时必须在配置中显式加入。BybitMarginMode / BybitPositionMode / BybitPositionIdxBybitMarginModeISOLATED_MARGIN逐仓、REGULAR_MARGIN普通全仓、PORTFOLIO_MARGIN组合保证金。BybitPositionModeMERGED_SINGLE单向持仓wire 值0与BOTH_SIDES双向持仓wire 值3。Python 绑定同时接受整数与字符串构造见 crates/adapters/bybit/src/python/enums.rs。BybitPositionIdxONE_WAY0、BUY_HEDGE1多头、SELL_HEDGE2空头。适配器在双向模式下将带positionIdx1/2的报表映射为以-LONG、-SHORT结尾的场外持仓 ID并在执行消息缺失positionIdx时将该 ID 带到成交上。其余常用枚举BybitAccountType目前为UNIFIED统一交易账户。BybitMarginActionBORROW/REPAY/GET_BORROW_AMOUNT现货保证金操作动作。BybitOrderTypeMARKET/LIMIT/UNKNOWN。BybitTimeInForceGtc/Ioc/Fok/PostOnly。BybitTriggerTypeLastPrice/IndexPrice/MarkPrice触发价格类型。BybitTpSlModeFull/PartialTP/SL 模式。BybitCancelType细粒度取消原因枚举覆盖CancelByUser、CancelByReduceOnly、CancelByCrossSelfMatch、CancelBySelfMatchPrevention等二十余种。底层 HTTP 客户端BybitHttpClient是面向 v5 REST 的高层客户端构造签名在 python/nautilus_trader/adapters/bybit/init.pyi 中可见参数包括api_key、api_secret、base_url、demo、testnet、timeout_secs60、max_retries3、retry_delay_ms1000、retry_delay_max_ms10000、recv_window_ms5000、proxy_url。其方法覆盖完整的数据与交易能力账户与配置get_account_details、set_leverage、switch_mode、set_margin_mode、request_fee_rates、request_account_state市场数据request_instruments、request_instrument_statuses、request_tickers、request_orderbook_snapshot、request_bars、request_funding_rates、request_trades交易submit_order、modify_order、cancel_order、cancel_all_orders、query_order、request_order_status_reports、request_fill_reports、request_position_status_reports现货保证金borrow_spot、repay_spot_borrow、repay_spot_borrow_with_conversion、get_spot_borrow_amountsubmit_order的参数极为丰富支持order_type、quantity、time_in_force、price、trigger_price、post_only、reduce_only、is_quote_quantity仅现货、is_leverage仅现货保证金、position_idx、bbo_side_type/bbo_levelBBO 订单、smp_type以及native_tp_slBybitNativeTpSlParams承载take_profit、stop_loss、tp_trigger_by、tp_limit_price、tpsl_mode、close_on_trigger、order_iv、mmp等原生 TP/SL 参数。BybitRawHttpClient则提供更底层的单端点封装如get_server_time、get_open_orders支持category、symbol、base_coin、settle_coin、order_id、order_link_id、open_only、order_filter、limit、cursor分页参数适合需要直接控制请求细节的高级调用者。订单参数体系与高级订单能力Bybit 适配器通过订单params字典把 Nautilus 订单映射为 v5 请求字段未设置的参数会从请求中省略从而交由 Bybit 自身默认值处理。常用参数一览参数类型说明is_leveragebool仅现货。启用保证金交易借款。默认Falsetake_profit/stop_lossstr/float原生 TP/SL 触发价tp_trigger_by/sl_trigger_bystr触发类型LastPrice/IndexPrice/MarkPricetp_order_type/sl_order_typestr执行类型Market/Limittp_limit_price/sl_limit_pricestr/float限价 TP/SL 的委托价tp_trigger_price/sl_trigger_pricestr/float显式自定义触发价tpsl_modestrFull/Partialclose_on_triggerbool触发时平仓position_idxint双向模式持仓索引0 单向 / 1 多 / 2 空bbo_side_typestr线性/反向 BBO 侧Queue/Counterpartybbo_levelstr/intBBO 档位1~5smp_typestr自成交预防order_ivstr/float期权按隐含波动率下单/改单mmpbool期权做市商保护原生 TP/SL 示例order strategy.order_factory.limit( instrument_idInstrumentId.from_str(BTCUSDT-LINEAR.BYBIT), order_sideOrderSide.BUY, quantityQuantity.from_str(0.01), pricePrice.from_str(60000.0), params{ take_profit: 65000.0, stop_loss: 58000.0, tp_trigger_by: LastPrice, sl_trigger_by: LastPrice, }, ) strategy.submit_order(order)适配器在发出OrderSubmitted前会本地校验参数违反规则即以VALIDATION_FAILED拒绝TP/SL 覆盖字段必须伴随对应take_profit/stop_losstp_order_typeLimit必须伴随tp_limit_price反之亦然bbo_side_type与bbo_level必须成对出现smp_type只能是四个合法值之一大小写不敏感匹配。若设置了 TP/SL 而未指定tpsl_mode则发送Full设置了价格而未指定触发类型时从订单的触发类型推导。BBO 订单order strategy.order_factory.limit( instrument_idInstrumentId.from_str(BTCUSDT-LINEAR.BYBIT), order_sideOrderSide.BUY, quantityQuantity.from_str(0.01), pricePrice.from_str(60000.0), params{bbo_side_type: Queue, bbo_level: 1}, ) strategy.submit_order(order)设置bbo_side_type与bbo_level后适配器发送 Bybit 的bboSideType与bboLevel字段并从 API 请求中省略订单价格。BBO 订单支持线性与反向的限价、止损限价与触价限价订单。自成交预防SMPconfig BybitExecutionClientConfig( api_keyYOUR_API_KEY, api_secretYOUR_API_SECRET, smp_typeCancelMaker, # 客户端级默认 ) # 单笔覆盖 params {smp_type: CancelBoth}四个合法值及其语义None不预防、CancelMaker撤掉挂单方、CancelTaker撤掉吃单方、CancelBoth双方都撤。适配器总是以规范拼写发送。配置与参数都未设置时省略smpType由 Bybit 自身默认处理。现货保证金交易order strategy.order_factory.market( instrument_idInstrumentId.from_str(BTCUSDT-SPOT.BYBIT), order_sideOrderSide.BUY, quantityQuantity.from_str(0.1), params{is_leverage: True}, # 启用保证金 ) strategy.submit_order(order)需要特别注意即便账户开启了自动借款未传is_leverageTrue的现货订单也不会动用保证金。此外close_on_trigger并非风险引擎的close_position全仓退出合约适配器发送的是订单数量因此不要将BYBIT加入full_position_exit_venues。订单能力矩阵按品类能力SpotLinearInverseOption备注MARKET/LIMIT✓✓✓✓报价数量仅现货STOP_MARKET/STOP_LIMIT/MARKET_IF_TOUCHED/LIMIT_IF_TOUCHED✓✓✓-期权不支持条件单TRAILING_STOP_MARKET----本地以UNSUPPORTED_ORDER_TYPE拒绝post_only✓✓✓✓仅限价类型映射为PostOnlyTIFreduce_only-✓✓✓现货不支持GTC/FOK/IOC✓✓✓✓GTD不支持按GTC发送订单修改✓✓✓✓支持价格与数量修改批量提交 / 批量撤单✓✓✓✓主网与测试网走 Trade WebSocket演示环境回落为逐笔 HTTP持仓查询 / 杠杆控制 / 保证金模式-✓✓✓(仅保证金模式)期权仅单向持仓、杠杆不可配适配器对不支持的订单类型会在本地以UNSUPPORTED_ORDER_TYPE拒绝不会发往交易所订单列表在发送任何腿之前整体校验任一条腿校验失败时其余腿以ORDER_LIST_DENIED拒绝杜绝部分提交。关于批量操作Bybit 单次批量请求上限为现货 10 笔、线性/反向 20 笔、期权 5 笔。适配器默认将现货/线性/反向批次按 10 笔分组、期权按 5 笔分组以适配 UID 配额。期权与行情数据期权采用CryptoOption合约类型与-OPTION符号后缀。实时行情通过 WebSocket ticker 频道提供买卖报价、希腊字母delta/gamma/vega/theta 与 bid/ask/mark IVBybit 不提供 rho、标记价、指数价、每到期日参考价、未平仓量以及来自期权订单簿流的 L2 MBP 增量。期权无 K 线数据。期权订单还可通过order_iv按隐含波动率下单/改单、通过mmp启用做市商保护这些参数在主网走 Trade WebSocket演示环境走 HTTP 创建订单端点演示环境不支持按order_iv改单。期权交易限制包括不可配置杠杆买方付权利金、卖方缴保证金、仅单向持仓、不支持条件单、不支持持仓级 TP/SL、无资金费率、必须使用统一交易账户UTA。对现货SPOT、线性LINEAR与反向INVERSE产品报价订阅使用 depth-1 订单簿快照10 ms 推送频率期权报价走 ticker 频道。深度订单簿增量只来自所订阅的深度同一合约同时只订阅一个深度。完整的实盘节点示例以下配置节选自已提交真实订单的执行测试器 examples/live/bybit/exec_tester.py展示了两个工厂与配置在LiveNode中的标准装配方式node ( LiveNode.builder(BYBIT-EXEC-TESTER-001, TRADER_ID, Environment.LIVE) .with_reconciliation(reconciliationTrue) .with_risk_engine_config(LiveRiskEngineConfig(bypassTrue)) .add_data_client( None, BybitDataClientFactory(), BybitDataClientConfig( product_typesPRODUCT_TYPES, # [BybitProductType.LINEAR] environmentBybitEnvironment.MAINNET, ), ) .add_exec_client( None, BybitExecutionClientFactory(), BybitExecutionClientConfig( product_typesPRODUCT_TYPES, environmentBybitEnvironment.MAINNET, account_idACCOUNT_ID, # BYBIT-001 ), ) .build() )该示例在启动时以 IOC 订单开仓随后在盘口两侧维持 post-only 限价报价停止时撤单并平仓注意它连接主网并使用真实资金仅用于执行链路验证而非生产策略。仓库还提供了 bybit_option_chain.py期权链快照、bybit_option_greeks.py期权希腊字母订阅与 data_tester.py行情测试等参考示例。总结NautilusTrader 的 Bybit 适配器把 Bybit v5 API 的复杂性收敛为一组类型安全、声明式的 Python 接口通过BybitDataClientConfig/BybitExecutionClientConfig声明环境、品类、凭证与传输行为通过工厂无缝接入LiveNode事件驱动架构通过订单params完整表达原生 TP/SL、BBO、SMP、保证金与期权特性并在本地完成参数校验与批量配额管理。底层实现与枚举定义可分别在 crates/adapters/bybit/src/python/config.rs、crates/adapters/bybit/src/common/enums.rs 与 crates/adapters/bybit/src/http/client.rs 中深入研读完整的集成说明见 docs/integrations/bybit.md。【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考