Nautilus Trader 永续合约建模指南CryptoPerpetual 字段、校验与交易适配器全解析【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader本文是 Nautilus Trader 领域模型nautilus_model中CryptoPerpetual合约类型的完整技术指南。CryptoPerpetual用于表示加密货币永续期货合约perpetual swap——一种无到期日、追踪某一加密基础资产、并以加密资产、稳定币或其他交易所定义货币结算的合约类型。读完本文你将掌握永续合约在 Rust 与 Python 双语言 API 下的完整字段语义、线性 / 反向 / Quanto 三种计价模式的区别、构造时的校验规则与默认值以及 Binance、BitMEX、OKX、Hyperliquid 等主流交易所适配器如何消费该类型从而能在自己的策略、回测与实盘节点中正确建模永续合约。什么是 CryptoPerpetual在 Nautilus Trader 中CryptoPerpetual是nautilus_model提供的第一类合约数据类型对应现实世界中的永续合约 / 永续掉期。与到期合约CryptoFuture、FuturesContract不同永续合约没有激活时间与到期时间持仓可以无限期滚动通过定期资金费率funding rate使合约价格锚定现货指数。典型示例仓库 crypto_perpetual.md 中给出ETHUSDT-PERP.BINANCE—— 币安 USD-M 永续线性、以 USDT 结算XBTUSD.BITMEX—— BitMEX 经典反向永续以 BTC 结算BTC-USD-SWAP.OKX—— OKX 永续掉期市场。在 Rust 侧该类型定义于 crypto_perpetual.rs是一个带#[repr(C)]布局、支持serde序列化、并在pythonfeature 下通过pyo3暴露为nautilus_trader.model.CryptoPerpetual的结构体。它实现了 Instrument trait 并作为InstrumentAny::CryptoPerpetual(...)变体参与统一分发见 any.rs。核心字段与完整语义CryptoPerpetual的全部字段如下表所示Rust / Python 类型映射与原文档保持一致并补充了源码中的默认值与语义说明字段Rust 类型Python 类型必填/默认说明instrument_idInstrumentIdInstrumentId必填全局唯一标识Rust 侧存储为id字段raw_symbolSymbolSymbol必填交易所原生符号如ETHUSDTbase_currencyCurrencyCurrency必填基础加密资产quote_currencyCurrencyCurrency必填报价计价货币settlement_currencyCurrencyCurrency必填结算 PnL 与手续费所用货币is_inverseboolbool必填是否为反向合约影响计价与成本货币price_precisionu8int必填价格允许的小数位size_precisionu8int必填订单数量允许的小数位price_incrementPricePrice必填最小有效价格步长tick sizesize_incrementQuantityQuantity必填最小有效数量步长ts_eventUnixNanosint必填事件时间戳纳秒ts_initUnixNanosint必填对象初始化时间戳纳秒multiplierQuantityQuantity默认1合约乘数lot_sizeQuantityQuantity默认1取整后的手数 / 板面大小max_quantityOptionQuantityQuantity \| None默认None最大订单数量min_quantityOptionQuantityQuantity \| None默认None最小订单数量max_notionalOptionMoneyMoney \| None默认None最大订单名义价值min_notionalOptionMoneyMoney \| None默认None最小订单名义价值max_priceOptionPricePrice \| None默认None有效报价 / 订单最高价min_priceOptionPricePrice \| None默认None有效报价 / 订单最低价margin_initOptionDecimalDecimal \| None默认0初始保证金率margin_maintOptionDecimalDecimal \| None默认0维持保证金率maker_feeOptionDecimalDecimal \| None默认0Maker 费率负值表示返佣taker_feeOptionDecimalDecimal \| None默认0Taker 费率负值表示返佣tick_schemeOptionUstrstr \| None默认None已注册的变步长variable tick方案名infoOptionParamsdict \| None默认None适配器附加元数据命名约定Python 构造函数使用instrument_id参数名而 Rust 结构体内部将该值存储为id字段两者等价文档与类型存根python/nautilus_trader/model/init.pyi中均遵循这一约定。行为规则资产类别、到期时间与计价模式CryptoPerpetual的行为由Instrumenttrait 的实现crypto_perpetual.rs严格定义资产类别与合约类别asset_class()恒为AssetClass::Cryptocurrencyinstrument_class()恒为InstrumentClass::Swap无到期activation_ns()与expiration_ns()均返回None这也是它与CryptoFuture的本质区别无衍生属性underlying、isin、option_kind、strike_price均返回None相等性与哈希PartialEq/Eq/Hash仅基于idcrypto_perpetual.rs同一合约的多次实例在集合中互等。线性、反向与 Quanto 合约线性合约Linearis_inverseFalse通常在报价货币中结算即settlement_currency quote_currency例如ETHUSDT-PERP.BINANCE反向合约Inverseis_inverseTrue通常在基础货币中结算例如 BitMEX 的XBTUSD测试test_inverse_perp_accessors断言其settlement_currency()与cost_currency()均为BTC见 crypto_perpetual.rsQuanto 合约以既非基础也非报价的第三种货币结算。成本货币cost currency的判定逻辑成本货币决定了下单与保证金计算所用币种其规则实现于 instruments/mod.rs反向合约 → 基础货币base_currency反向合约必有基础货币否则 panicQuanto 合约 → 结算货币settlement_currency其他情况 → 报价货币quote_currency。而is_quanto()的判定instruments/mod.rs为结算货币既不同于基础货币又与报价货币不等价。其中USD 等价货币集合包括BUSD、FDUSD、pUSD、TUSD、USD、USDC、USDC.e、USDP、USDTinstruments/mod.rs这意味着ETH/USDT永续若以USDC结算不会被误判为 Quanto。重要资金费率funding payment不是合约字段而是以数据对象的形式到达例如FundingRateUpdate并通过instrument_id引用对应合约。相关数据模型见 funding.rs。构造校验字段一致性由编译期与运行时双重保证CryptoPerpetual的构造无论是位置参数new_checked还是流畅 Buildercrypto_perpetual.rs会执行以下正确性检查任一失败即返回Err精度一致性price_precision必须等于price_increment.precisionsize_precision必须等于size_increment.precision对应测试test_new_checked_price_precision_mismatch与test_new_checked_size_precision_mismatch正值约束price_increment必须为正价格、size_increment必须为正数量乘数与手数multiplier与lot_size若提供则必须为正test_new_checked_rejects_non_positive_sizing断言错误信息包含not positivetick schemetick_scheme若提供则必须在已注册方案中存在check_tick_scheme。可选字段省略时的默认值由unwrap_or_default系列实现测试test_builder_applies_defaults_for_omitted_optionals验证multiplier 1、lot_size 1margin_init、margin_maint、maker_fee、taker_fee均为0max_quantity、min_notional、tick_scheme、info等均为None。Builder 在build()时执行与new_checked完全相同的校验test_builder_propagates_validation_error证实精度不匹配会被 Builder 拒绝并支持maybe_*变体 setter如maybe_min_notional。此外合约支持 JSON 序列化往返test_serialization_roundtrip。Rust 构建示例ETHUSDT-PERP.BINANCE以下代码完整构建一个币安 USD-M 线性永续合约并包装为InstrumentAny来源crypto_perpetual.md 示例可原样编译运行use nautilus_core::UnixNanos; use nautilus_model::{ identifiers::{InstrumentId, Symbol}, instruments::{CryptoPerpetual, InstrumentAny}, types::{Currency, Money, Price, Quantity}, }; use rust_decimal_macros::dec; let ethusdt_perp CryptoPerpetual::builder() .instrument_id(InstrumentId::from(ETHUSDT-PERP.BINANCE)) .raw_symbol(Symbol::from(ETHUSDT)) .base_currency(Currency::from(ETH)) .quote_currency(Currency::from(USDT)) .settlement_currency(Currency::from(USDT)) .is_inverse(false) .price_precision(2) .size_precision(3) .price_increment(Price::from(0.01)) .size_increment(Quantity::from(0.001)) .max_quantity(Quantity::from(10000.000)) .min_quantity(Quantity::from(0.001)) .min_notional(Money::from(10.00 USDT)) .max_price(Price::from(15000.00)) .min_price(Price::from(1.00)) .margin_init(dec!(1.0)) .margin_maint(dec!(0.35)) .maker_fee(dec!(0.0002)) .taker_fee(dec!(0.0004)) .ts_event(UnixNanos::default()) .ts_init(UnixNanos::default()) .build() .unwrap(); let instrument InstrumentAny::CryptoPerpetual(ethusdt_perp);值得注意该示例中price_increment 0.01两位小数与price_precision 2严格一致size_increment 0.001与size_precision 3一致——这正是上文校验规则 #1 的实践体现。margin_init 1.0表示开仓保证金为订单名义价值的 100%margin_maint 0.35为维持保证金率百分数表示maker_fee 0.0002、taker_fee 0.0004为费率若为负值则代表返佣。Python 构建示例Python 侧等价构造来源同上注意 Python 构造顺序中ts_event、ts_init紧随必填字段之后才是全部可选参数与init.pyi 存根签名一致from decimal import Decimal from nautilus_trader.model import CryptoPerpetual from nautilus_trader.model import Currency from nautilus_trader.model import InstrumentId from nautilus_trader.model import Money from nautilus_trader.model import Price from nautilus_trader.model import Quantity from nautilus_trader.model import Symbol ETH Currency.from_str(ETH) USDT Currency.from_str(USDT) ethusdt_perp CryptoPerpetual( instrument_idInstrumentId.from_str(ETHUSDT-PERP.BINANCE), raw_symbolSymbol(ETHUSDT), base_currencyETH, quote_currencyUSDT, settlement_currencyUSDT, is_inverseFalse, price_precision2, size_precision3, price_incrementPrice.from_str(0.01), size_incrementQuantity.from_str(0.001), ts_event0, ts_init0, max_quantityQuantity.from_str(10000.000), min_quantityQuantity.from_str(0.001), min_notionalMoney(10.00, USDT), max_pricePrice.from_str(15000.00), min_pricePrice.from_str(1.00), margin_initDecimal(1.0), margin_maintDecimal(0.35), maker_feeDecimal(0.0002), taker_feeDecimal(0.0004), )实例创建后可访问symbol、venue、id、raw_symbol、is_quanto、asset_class、instrument_class等属性以及各精度 / 增量 / 保证金字段的属性访问器均以property暴露见init.pyi。在回测与实盘中的角色精度与名义价值检查CryptoPerpetual不只是数据容器——订单在下发交易所之前执行引擎会利用其中的精度与限额字段做校验。以 binance 期货执行客户端 为例其逻辑会区分CryptoPerpetual/CryptoFuture等衍生品合约类型并按合约的price_precision、size_precision、min_notional、max_price、min_price等字段对订单价格与数量进行取整与限额检查cost_currency则决定了保证金与费用以何种货币计价。这意味着合约元数据配置得越精确回测与实盘的风险前置检查就越可靠。适配器支持以下是创建或消费CryptoPerpetual的具有代表性的适配器仓库源码中均可检索到CryptoPerpetual的直接引用BinanceUSD-M 与 COIN-M 永续合约binance/src/futures/execution.rs、binance/src/common/parse.rsBitMEX反向与线性永续合约bitmex/src/http/parse.rsBybit线性与反向永续产品bybit/src/common/instruments.rsdYdX永续市场dydx/src/data.rsHyperliquid永续市场hyperliquid/src/http/parse.rsKraken期货交易所永续市场kraken/src/common/parse.rsOKX永续掉期市场okx/src/common/parse.rsTardis加密永续合约元数据tardis/src/http/instruments.rs。此外Deribit、Coinbase、Lighter、Derive 等适配器也直接构建或使用该类型如 deribit/src/data.rs、lighter/src/http/parse.rs。各适配器负责将交易所原始 REST / WebSocket 行情中的合约元数据解析为统一的CryptoPerpetual从而让上层策略与引擎不感知交易所差异。相关指南数据概念Data涵盖标记价格mark price、指数价格index price与资金费率更新funding rate updates等与永续合约配套的数据类型期权概念Options期权特有合约类型CryptoOption等与此处永续合约的区别执行概念Execution订单到达交易所前的精度与名义价值检查流程理解price_precision、min_notional等字段如何实际生效。如需查看合约类型源码的全貌可进一步阅读 crates/model/src/instruments/crypto_perpetual.rs、Instrument trait 定义 以及测试夹具 stubs.rs其中包含crypto_perpetual_ethusdt与xbtusd_bitmex两个可直接复用的标准示例。【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
