Derive

Derive (formerly Lyra) is a decentralized derivatives venue offering European-style options and cash-settled perpetual swaps, and one of the largest on-chain options markets. Trading runs against a per-user smart-contract wallet on the Derive Chain, so collateral stays in the user's custody while orders match through the venue's orderbook.

The Derive Chain is an optimistic rollup that settles to Ethereum. Orders match off chain and settle on chain, pairing orderbook execution with self-custody. Orders are authorized with EIP-712 typed-data signatures from a session key scoped to a subaccount, which keeps the signing key separate from the wallet owner and lets users rotate or revoke access without moving funds.

Overview

The Derive adapter is implemented in Rust under crates/adapters/derive. It exposes:

• DeriveHttpClient: Low-level REST connectivity to api.lyra.finance (mainnet) or api-demo.lyra.finance (testnet).
• DeriveWebSocketClient: JSON-RPC WebSocket transport with subscription tracking, reconnect, and signed order entry.
• DeriveInstrumentProvider: Per-currency instrument fetch and caching.
• DeriveDataClient: Live market data client.
• DeriveDataClientFactory: Data client factory for the live node builder.
• DeriveExecutionClient: Live execution client for signed order, cancel, query, and report flows.
• DeriveExecutionClientFactory: Execution client factory for the live node builder.

Execution flows use EIP-712 typed-data signing against the Derive Chain per-action module contracts.

Python surface available from nautilus_trader.adapters.derive:

• DeriveDataClientConfig, DeriveExecClientConfig, DeriveExecFactoryConfig
• DeriveDataClientFactory, DeriveExecutionClientFactory
• DeriveEnvironment
• DERIVE, DERIVE_CLIENT_ID, and DERIVE_VENUE

Examples

• Python examples
• Rust examples

Derive documentation

Derive publishes API documentation at docs.derive.xyz. Refer to it alongside this guide for additional details.

Products

Symbology

Derive instruments use the native venue symbol with the venue suffix .DERIVE:

• Spot: ETH-USDC.DERIVE (base currency, quote currency).
• Perpetual: ETH-PERP.DERIVE, BTC-PERP.DERIVE.
• Option: ETH-20260626-3000-C.DERIVE (currency, expiry, strike, kind).

The first hyphen-separated segment of the symbol is the underlying currency. The provider fetches public/get_instruments once per currency, so subscribing to a new currency triggers a lazy REST fetch when auto_load_missing_instruments is enabled (the default).

The adapter routes on the venue instrument_type (perp, option, erc20), not on the symbol suffix, so spot pairs need no special symbology parsing. Spot reuses the same Trade-module signing path as perps and options; the in-repo fixtures under crates/adapters/derive/test_data/spot/ capture the spot instrument, order book, ticker, and trade field shapes the parser and execution paths are pinned to.

Environments

Configure the environment with the DeriveEnvironment enum on either client config.

Testnet is a separate chain with its own session keys and balances; mainnet and testnet API keys are not interchangeable. Public market data (book, ticker, trades) does not require credentials.

The EIP-712 protocol constants (DOMAIN_SEPARATOR, ACTION_TYPEHASH, per-action module addresses) for both networks are shipped in crates/adapters/derive/src/common/consts.rs and tracked against Derive's Protocol Constants reference. DeriveExecClientConfig::domain_separator, action_typehash, and trade_module_address accept per-instance overrides that take precedence over the shipped values.

Testnet onboarding

Derive labels the demo environment "testnet" in the web app and "demo" in the API hostname. This guide uses "testnet" to match the dashboard and our DeriveEnvironment::Testnet enum. Steps to reach a position where the execution client can submit a signed order:

1. Sign in to the testnet dashboard. Open testnet.derive.xyz and connect an EVM wallet (MetaMask, WalletConnect, social login, etc.). This is the owner EOA that authorizes the smart-contract wallet below.

2. Register the Derive Chain smart-contract wallet. First sign-in deploys a per-user smart-contract wallet on the Derive testnet chain. The address shown under "Developers" -> "Derive Wallet" is the wallet_address (and the X-LYRAWALLET header) the client uses. It is distinct from the EOA you just connected.

3. Create a subaccount. Open a subaccount under the wallet (Standard Margin is the simplest mode for test trading). The integer id is the subaccount_id the client signs each private/order request against.

4. Generate a session key. Under "Developers" -> "Session Keys", create a session key scoped to the subaccount and copy the raw secp256k1 private key. This is the session_key value; it never leaves the client and is redacted from Debug output. Session keys can be rotated or revoked from the same panel.

5. Fund the subaccount via the faucet. The testnet dashboard exposes a USDC faucet that drips test collateral. Deposit into the subaccount so the on-chain balance shows non-zero collateral; the API will reject orders until the subaccount has enough margin for the requested size.

6. Set the environment variables. Export the three values the client reads in testnet mode (or pass them on DeriveExecClientConfig, where the config field wins):

   export DERIVE_TESTNET_WALLET_ADDRESS="0x..."  # Derive Chain smart-contract wallet
   export DERIVE_TESTNET_SESSION_PRIVATE_KEY="0x..."  # secp256k1 session-key private key
   export DERIVE_TESTNET_SUBACCOUNT_ID="12345"  # integer subaccount id

Minimum funding

There is no fixed venue minimum. The matching engine accepts any order that satisfies the subaccount's initial-margin requirement for the resulting position. Treat these as practical floors for the smallest viable test:

• Smoke test (submit and cancel, no fills): any positive USDC balance covers the signed-order plumbing.
• Round-trip an ETH-PERP fill: budget for the worst-case slippage-adjusted notional plus the initial-margin cushion. For one contract at $3500 and the venue's ~10% IM, that is roughly $350 collateral plus $400 cushion. Around $1000 USDC is a comfortable working balance for a first-fill test.
• Options: options carry higher IM than perps. Pull public/get_instrument for the option, multiply the contract size by mark price, then add the option-specific IM (visible on the instrument response) before sizing the deposit.

Use the private/get_subaccount endpoint after funding to confirm initial_margin stays positive once the intended order's initial margin is applied: initial_margin and maintenance_margin are the subaccount's signed net health (collateral credit minus the corresponding requirement), the venue rejects risk-increasing orders that would drive initial_margin negative, and a negative maintenance_margin exposes the subaccount to liquidation. The adapter's query_account command emits this snapshot as an AccountState event so the strategy layer can gate trading on it.

Mainnet onboarding

Mainnet onboarding mirrors testnet against the production dashboard. Use real funds.

1. Sign in to the mainnet dashboard. Open derive.xyz and connect the EVM owner wallet (MetaMask, WalletConnect, social login, etc.). First sign-in deploys your Derive Chain smart-contract wallet.

2. Copy the wallet address. Under "Developers" -> "Derive Wallet", copy the smart-contract wallet address. This is the wallet_address the client signs against; it is distinct from the EOA you signed in with. Verify on the Derive Chain explorer that the address has contract code (EOAs do not).

3. Create or pick a subaccount. Open a subaccount under the wallet (Standard Margin is the simplest mode; switch to Portfolio Margin only once you understand the cross-margin semantics). The integer id is the subaccount_id.

4. Generate a mainnet session key. Under "Developers" -> "Session Keys", create a session key scoped to the subaccount and copy the raw secp256k1 private key. Session keys can be rotated or revoked from the same panel; prefer short-lived keys for exploratory tester runs.

5. Fund the subaccount. Deposit USDC (or supported collateral) into the subaccount via the dashboard's deposit flow. Confirm via private/get_subaccount (or the adapter's query_account) that the deposit lands in collaterals_value and initial_margin stays positive after the intended order.

6. Set the environment variables. Export the three mainnet values (or pass them on DeriveExecClientConfig, where the config field wins):

   export DERIVE_WALLET_ADDRESS="0x..."  # Derive Chain smart-contract wallet
   export DERIVE_SESSION_PRIVATE_KEY="0x..."  # secp256k1 session-key private key
   export DERIVE_SUBACCOUNT_ID="12345"  # integer subaccount id

   Each Rust example (node_data_tester, node_exec_tester, node_delta_neutral) pins the network with a const DERIVE_ENVIRONMENT: DeriveEnvironment literal near the top of the file. Check that constant before every run and edit it to switch networks; the examples do not read the network from the environment. Production deployments select the network via DeriveDataClientConfig::environment / DeriveExecClientConfig::environment.

Referral code attribution

Every signed order, replace, and trigger order carries the hard‑coded NautilusTrader referral code. Derive funds the referral program from its own revenue, so attribution adds no trading cost, needs no approval, and is not configurable. This helps us gauge real usage of the integration and prioritize ongoing maintenance.

Capabilities

Market data

request_instrument calls public/get_instrument for the requested InstrumentId and caches the returned definition before emitting the response. The cached instrument carries the precision and increment fields used by later quote, trade, book, and bar parsing.

Instrument loading treats venue error 12001 as an empty result for the affected product type, so a currency without a perp, option, or spot listing does not block its other products. Invalid instrument rows are logged and skipped while valid rows continue to load.

Historical requests use public/get_trade_history, public/get_tradingview_chart_data, and public/get_funding_rate_history. The bar end bound still selects buckets by their start time at the venue. Responses omit any bucket whose close is after the request time, including the still-forming bucket returned by the venue. Trade history returns one maker row and one taker row per trade under the same trade_id, and each row's direction is that participant's own side, while the public WS trades feed defines direction as the taker's side. Trade requests emit one TradeTick per trade whose aggressor side is the taker's direction, independent of row order; rows with an absent or unknown liquidity_role fall back to treating direction as the taker's side.

Bars require EXTERNAL aggregation and PriceType::Last, since Derive candles are trade-based. The venue's candle periods map to 1, 5, 15, and 30 minute, 1, 4, and 8 hour, 1 day, and 1 week steps; any other bar specification is rejected before the request goes out.

Derive exposes book deltas and depth10 snapshots through the same orderbook.{instrument}.{group}.{depth} channel family. subscribe_book_deltas publishes snapshot deltas as OrderBookDeltas, while subscribe_book_depth10 fixes depth=10 and publishes OrderBookDepth10 snapshots.

Execution

Order placement, cancellation, modification, query, and report generation use Derive's EIP-712 self-custodial signing flow. Order-entry writes (private/order, private/trigger_order, private/replace, private/cancel, private/cancel_trigger_order, private/cancel_by_label, private/cancel_all) go over the WebSocket on the same authenticated session that streams account, order, trade, and balance state through the private channels ({subaccount_id}.orders, {subaccount_id}.trades, {subaccount_id}.balances). The signed EIP-712 body is identical regardless of transport.

Perpetuals, options, and ERC-20 spot pairs all use the Derive Trade module. Spot has no separate signing path, and reconciliation treats spot instruments like other instrument classes except for the reduce-only guard described below.

The adapter supports ordinary private/order requests: LIMIT and MARKET orders with GTC, IOC, or FOK time-in-force values. It also supports Derive trigger orders for the Nautilus-native stop and if-touched order types listed below. Unsupported Nautilus order types are denied locally with OrderDenied before submission, so they cannot fill at the venue.

Market orders require a cached quote before submission; without one the adapter emits OrderDenied and never signs. After the async submit task resolves the instrument, it refreshes the current ticker snapshot and derives the signed slippage-bound limit_price from that refreshed quote.

Account state

Derive holds margin at the subaccount level, so the AccountState mapping is:

• Balances: total is the collateral amount (for example USDC or ETH) in its native units and locked is zero, because the venue reports no per-collateral reservation. collaterals[].initial_margin is USD credit contributed by that collateral, not locked funds.
• Margins: one account-wide MarginBalance where initial = positions_initial_margin + open_orders_margin and maintenance = positions_maintenance_margin. These venue fields are USD requirements, stamped with the subaccount currency. Immediately after a closing trade the venue can transiently report negative positions_*_margin values equal to the not‑yet‑settled cash movement (realized PnL and fees); the fields return to zero once settlement lands in the collateral balance. Gate trading on net_initial_margin / net_maintenance_margin in AccountState.info, not on these requirement fields.
• Info: the subaccount's signed net health is not a margin requirement, so it travels in the AccountState.info map as net_initial_margin and net_maintenance_margin alongside positions_initial_margin, positions_maintenance_margin, open_orders_margin, and is_under_liquidation. Decimal values are JSON strings.

Conditional orders

Derive trigger orders use the WebSocket-only private/trigger_order endpoint, not the normal private/order endpoint. The venue stores them with order_status=untriggered until its trigger worker submits the signed child order. Reconciliation therefore reads both private/get_open_orders and private/get_trigger_orders.

Derive mainnet requires trigger-order signatures to expire 30 to 90 days from venue time. The adapter signs trigger orders with a fixed 31-day expiry; signature_expiry_secs still controls ordinary private/order and private/replace writes, and must be greater than the 300s venue minimum.

The adapter maps Nautilus TriggerType::Default and TriggerType::MarkPrice to Derive trigger_price_type=mark. Derive's current error-code reference states that index and last-trade trigger price types are not supported yet, so IndexPrice, LastPrice, BidAsk, and other trigger price types are denied locally with OrderDenied before submission.

Derive error 11054 states that trigger orders cannot replace or be replaced. The adapter therefore rejects Nautilus modify requests for trigger orders with an OrderModifyRejected event; cancel and resubmit for trigger updates.

Derive validates the trigger price side and rejects a trigger that does not sit beyond the current price in the expected direction with error 11051. The trigger price is fixed when the order is signed, so a tight offset on a fast-moving or high-priced instrument can drift onto the wrong side before the venue receives the order. Size the trigger offset to comfortably exceed expected price movement during submission (for ETH-PERP, tens of dollars rather than a few cents); a too-tight offset produces spurious 11051 rejections.

Execution instructions

Time in force

Derive documents gtc, post_only, fok, and ioc as its time_in_force values. Nautilus values with no Derive equivalent are denied locally with OrderDenied before submission. Derive exposes post-only as a time_in_force value, so post_only cannot combine with IOC or FOK.

Spot reduce-only orders

Derive spot has no position concept, so a reduce-only spot order can never reduce anything. The venue always rejects it with error 11025; the adapter avoids that round-trip when it knows the instrument is spot. Cached spot instruments are denied with OrderDenied; lazily resolved spot instruments are rejected with OrderRejected during submit.

Reduce-only orders for perpetuals and options still reach the venue, where the outcome depends on the subaccount's position state. The derive-flatten bin closes derivative positions only and never spot, since flattening a spot balance would dump the base asset into a different quote.

Derive only honors reduce_only on market orders or non-resting limits (IOC/FOK). A resting GTC or post-only limit with reduce_only is rejected by the venue with error 11024 Reduce only not supported with this time in force. As a result a Nautilus bracket whose take-profit leg is a reduce-only GTC limit cannot rest on Derive: the entry and stop-loss legs submit, but the take-profit is rejected. Use a reduce-only IOC/FOK close or a non-reduce-only take-profit when targeting Derive.

Order rejection semantics

State-changing writes (submit_order, modify_order, cancel_order) are sent once over the WebSocket and are not replayed. The adapter keys terminal vs ambiguous handling off the WebSocket request outcome. It emits a terminal rejection event (OrderRejected, OrderModifyRejected, OrderCancelRejected) for definitive venue failures:

• Signed-action rejections such as invalid params, insufficient margin, or unknown orders.
• Venue business codes such as 11009 Zero liquidity.
• Post-only crossing rejections (11008 Post only order cannot cross the market), reported as OrderRejected with due_post_only=true.
• Rate-limit responses (-32000 Rate limit exceeded), where the gateway rejects the request before the matching engine sees it.
• A successful private/cancel_by_label response with cancelled_orders == 0, which means no open order matched the client order ID label.

For other cancelled_orders values, the adapter emits no terminal event and waits for the venue order notification or later reconciliation to settle the state. The venue may return cancelled_orders == -1 for a cancel that matched its label‑wildcard path; this is treated as success and settled the same way.

For post-only orders that reach the venue, Derive rejects a crossing order with JSON-RPC 11008 and message Post only order cannot cross the market. The adapter marks that terminal rejection with due_post_only=true; if a WebSocket/order-report rejection carries the same reason, the tracked order path applies the same classification. Local denials for unsupported post-only IOC/FOK combinations are OrderDenied events without due_post_only, because they do not represent a venue crossing rejection.

For ambiguous write outcomes, the adapter emits no terminal event and lets WebSocket reconciliation or later status reports settle the state. The ambiguous set is deliberately narrow:

• -32603, a generic JSON-RPC internal error.
• A response that cannot be decoded (the action may have been processed).
• Request timeouts, dropped responses on reconnect, and transport errors.

This distinction protects both sides of the order lifecycle. A false terminal rejection can make the engine treat a live order as rejected; a false ambiguous outcome can leave an unplaced order hanging in Submitted forever because no WebSocket frame will arrive.

Rate limiting

Derive refills every request allowance discretely at fixed five‑second window boundaries, not one request at a time (source: venue rate limits). The adapter mirrors this with a fixed‑window limiter: each request class may spend its full window allowance in one burst, and the next request waits for the boundary before it can depart.

Windows are aligned to client construction because the venue's own window phase cannot be observed from the client, so a wait is at most one full window and the long‑run average rate stays at the venue allowance. A burst can still straddle a venue window boundary, in which case the venue answers with -32000 Rate limit exceeded, which the adapter surfaces as a definitive rejection (see order rejection semantics).

Each window allowance is the documented requests‑per‑second rate times the five‑second window, so the configured max_matching_requests_per_second and max_per_instrument_matching_requests_per_second (1 each for Trader) admit five requests per window:

The REST per‑IP allowance is flat across tiers. The WebSocket non‑matching allowance applies to sessions authorized via public/login; the venue applies a reduced, unspecified allowance to unauthenticated sessions, so public data‑client traffic can hit venue limits earlier. The venue also caps concurrent WebSocket connections per IP (4 for a Trader).

Matching‑engine writes that carry an instrument (order, replace, trigger order, and instrument‑scoped cancel) draw on both the account‑wide matching bucket and that instrument's independent bucket, so a Market Maker's account‑wide override never inflates the per‑instrument allowance. Trigger order create and cancel methods are paced as matching writes even though the venue does not list them explicitly; private/cancel_trigger_order carries no instrument and draws on the account‑wide bucket only. The stricter classification stays on the safe side of the documented contract.

Pacing waits happen before the request is signed, so a delay never consumes the validity of the REST X-LYRA* authentication headers or of the nonces and EIP‑712 signatures on the WebSocket order path. A matching write whose window rolls between signing and dispatch is re‑paced once before departing (at most one further window, covered by the >300s signature TTL). A venue rate‑limit response remains a definitive rejection; see order rejection semantics.

The remaining live allowances can be checked manually over the WebSocket via private/getRateLimits; the adapter does not call it.

WebSocket recovery

The data and execution clients reconnect automatically after a peer close, transport error, or heartbeat timeout. The adapter sends protocol Ping frames every 30 seconds and treats 60 seconds without any inbound frame as a dead connection; the selected transport can report a missed Pong sooner. The transport retries connections with exponential backoff and jitter.

Recovery completes in this order:

1. The transport reconnects. If another disconnect occurs, recovery follows the latest connection.
2. Credentialed sessions log in again, then every session replays its confirmed subscriptions. Acknowledged unsubscriptions are not replayed.
3. The execution client refreshes account state and generates mass status for orders, fills, and positions.

State-changing requests follow the order rejection semantics: the adapter sends them once and never replays them. After three failed login or subscription recovery attempts, the client logs the error, marks itself disconnected, and stops that WebSocket session.

ws_timeout_secs applies to individual WebSocket operations, not heartbeat detection or reconnect backoff.

Subscription parameters

subscribe_book_deltas and subscribe_book_depth10 accept these subscribe_params keys:

subscribe_quotes accepts:

Unknown values are rejected at subscribe time.

Shared ticker subscription

Quotes, mark prices, index prices, funding rates, and option greeks are all derived from the same ticker_slim.{instrument}.{interval} WebSocket subscription. The adapter reference-counts the underlying WS subscribe call: the first feed subscribed for an instrument opens the channel and the last unsubscribe closes it. As a consequence, the interval from the first subscribe wins; subsequent feeds subscribing with a different interval share the existing channel.

Mark prices, index prices, funding rates, and option greeks read fields from the ticker payload. Both the full ticker shape and the compact ticker_slim shape carry these fields, so the derived feeds work on either: mark_price and index_price are required (a frame missing them fails to deserialize and is logged, rather than silently dropped), while funding_rate and option_pricing are optional and present only for the relevant instrument class. The quote feed always works because bid/ask are present in both shapes.

Funding rates are only meaningful for perpetuals, and option greeks only for options. Subscribing the wrong feed for an instrument's class (e.g. funding rates for an option) is accepted and the WebSocket subscription opens, but the parser returns no events for that feed because the venue payload omits the funding rate field for non-perps and option_pricing for non-options. Verify the instrument class before subscribing to derivative-specific feeds.

Configuration

Data client configuration options

Class/struct: DeriveDataClientConfig.

auto_load_missing_instruments covers subscribe commands only. The request commands (request_quotes, request_trades, request_bars, request_funding_rates, and request_forward_prices) fail when the instrument is not already cached, so bulk-load its currency or subscribe first. request_instrument is the exception: it always fetches public/get_instrument.

Execution client configuration options

Class/struct: DeriveExecClientConfig.

The default transport falls back to Tungstenite when the build disables the transport-sockudo feature.

The wallet_address, session_key, and subaccount_id fall back to environment variables when unset:

The session key is the secp256k1 private key registered on the wallet for API signing. The session_key field is redacted in Debug output and Python repr.

Python live node

Python nodes use LiveNode.builder(...) and pass concrete factory instances. The execution factory needs DeriveExecFactoryConfig, which wraps the trader and account identifiers with the underlying DeriveExecClientConfig.

from decimal import Decimal

from nautilus_trader.adapters.derive import DeriveDataClientConfig
from nautilus_trader.adapters.derive import DeriveDataClientFactory
from nautilus_trader.adapters.derive import DeriveEnvironment
from nautilus_trader.adapters.derive import DeriveExecClientConfig
from nautilus_trader.adapters.derive import DeriveExecFactoryConfig
from nautilus_trader.adapters.derive import DeriveExecutionClientFactory
from nautilus_trader.common import Environment
from nautilus_trader.live import LiveNode
from nautilus_trader.model import AccountId
from nautilus_trader.model import TraderId

trader_id = TraderId("TESTER-001")

data_config = DeriveDataClientConfig(
    environment=DeriveEnvironment.TESTNET,
    currencies=["ETH", "BTC"],
)

exec_config = DeriveExecClientConfig(
    environment=DeriveEnvironment.TESTNET,
    max_fee_per_contract=Decimal("1000"),
)

exec_factory_config = DeriveExecFactoryConfig(
    trader_id,
    AccountId("DERIVE-001"),
    exec_config,
)

node = (
    LiveNode.builder("DERIVE-001", trader_id, Environment.LIVE)
    .add_data_client(None, DeriveDataClientFactory(), data_config)
    .add_exec_client(None, DeriveExecutionClientFactory(), exec_factory_config)
    .build()
)

Do not pass DeriveExecClientConfig directly to add_exec_client; the Derive execution factory requires the wrapped DeriveExecFactoryConfig so it can create the ExecutionClientCore with the correct trader and account identifiers.

Rust data client

use nautilus_derive::{
    common::enums::DeriveEnvironment,
    config::DeriveDataClientConfig,
};

let config = DeriveDataClientConfig {
    environment: DeriveEnvironment::Testnet,
    currencies: vec!["ETH".to_string(), "BTC".to_string()],
    ..Default::default()
};

Rust execution client

use nautilus_derive::{
    common::enums::DeriveEnvironment,
    config::DeriveExecClientConfig,
};
use rust_decimal::Decimal;

let config = DeriveExecClientConfig {
    wallet_address: Some("0x...".to_string()),
    session_key: Some("0x...".to_string()),
    subaccount_id: Some(1),
    environment: DeriveEnvironment::Testnet,
    max_fee_per_contract: Some(Decimal::from(1000)),
    ..Default::default()
};

max_fee_per_contract is required and must be greater than zero. Execution-client construction fails before creating venue clients when the field is missing or non-positive.

Known limitations

• request_instruments requires at least one configured currency in DeriveDataClientConfig::currencies; the venue's public/get_instruments endpoint is scoped per-currency and the adapter does not enumerate the currency universe.
• The venue does not push instrument status, instrument close, or candle subscriptions; the instrument definition carries is_active and the scheduled activation/deactivation timestamps, and bars are REST-only.
• The book snapshot REST endpoint and historical book deltas / historical quote endpoints are not exposed by the venue. See the capabilities table above.
• Derive's official REST docs mark public/get_ticker as deprecated in favor of public/get_tickers as of December 1, 2025. The adapter uses public/get_tickers for quote snapshots and option-chain forward-price bootstrap.