feat: Add options contract holdings parsing & mark pricing support for Derive exchange

[halfdoctor]

Description

This PR introduces support for parsing, valuation, and mark pricing of options contract holdings (specifically targeting options on the Derive exchange connector and generalizing generic ticker row handling).

Motivation

Options instruments (e.g. ETH-20260925-3000-C) require custom handling compared to standard spot assets:

1. Standard spot ticker feeds don't list explicit trading pairs like ETH-20260925-3000-C-USDC.
2. Option symbol strings containing "USD" (such as option contracts quoted in USD) were previously at risk of being treated as $1.00 USD stablecoins by default.
3. Option positions and collateral balances need to be extracted together from exchange account endpoints.

---

Key Changes

1. services/accounts_service.py

• Added derive_options Quote Mapping: Mapped "derive_options": "USDC" in default QUOTE_ASSETS.
• Refined Stablecoin Check ("USD" in token and "-" not in token): Prevents option symbols containing "USD" (e.g., options contracts) from being hardcoded to a $1.00 valuation.
• Added Custom Token Price Hook (connector.get_token_price(token)): Allows connectors (like options exchanges) to return mark prices directly for non-standard assets, safely casting to Decimal.

2. services/ticker_sources.py

• Extended Key Mappings: Added "instrument_name" to _SYMBOL_KEYS, and "best_bid", "best_bid_price", "best_ask", "best_ask_price" to bid/ask keys.
• Nested Dict Unpacking in _heuristic_rows: Flattens nested "symbol" dictionaries (e.g., {"symbol": {"instrument_name": "ETH-PERP"}, ...}) so generic ticker adapters can process options and perps feeds without error.

3. utils/patch_derive_connector.py

• Connector Patch Script: Updates DeriveExchange._update_balances() to pull positions (active options and perps) alongside collaterals from /api/v1/private/get_subaccount. Exposes get_token_price() and get_option_positions() for Greeks and mark price metadata.

4. test/test_derive_options_integration.py

• Integration & Unit Tests: Added unit tests covering Derive positions payload parsing, mark price retrieval, Greeks metadata, and AccountsService token info integration (using scrubbed test credentials).

---

Verification & Testing

• Verified AccountsService option mark price resolution using custom connector hook.
• Verified _heuristic_rows parsing with nested symbol dictionary structures.
• Unit test suite added in test/test_derive_options_integration.py passing with mock responses.
• All test credentials scrubbed and environment-gated with pytest.importorskip("hummingbot").

[greptile-apps]

Greptile Summary

The PR adds Derive option-position balances, mark-price valuation, and generic parsing for ticker payloads containing nested instrument metadata.

• Applies the Derive connector monkey patch during application startup.
• Tracks option positions and exposes cached mark prices and Greeks.
• Allows account valuation to use connector-provided token prices.
• Extends generic ticker parsing for Derive-style symbols and bid/ask fields.
• Updates tests to apply the patch and execute asynchronous cases correctly.

Confidence Score: 5/5

The PR appears safe to merge because the previously reported startup and test-integration failures have been addressed and no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
main.py	Applies the Derive options patch before application services and connector instances are initialized.
services/accounts_service.py	Adds Derive options quote configuration and connector-specific mark-price resolution while retaining existing market-data fallbacks.
services/ticker_sources.py	Extends generic ticker field recognition and flattens nested symbol objects in list payloads.
utils/patch_derive_connector.py	Adds the runtime Derive connector patch for position balances, option metadata, and mark-price lookup.
test/test_derive_options_integration.py	Tests patched Derive position parsing and account valuation with the required async markers and patch setup.

Sequence Diagram

sequenceDiagram
    participant Startup as Application startup
    participant Patch as Derive patch
    participant Derive as DeriveExchange
    participant Accounts as AccountsService
    Startup->>Patch: apply_derive_options_patch()
    Patch->>Derive: install patched initialization and balance methods
    Accounts->>Derive: _update_balances()
    Derive-->>Accounts: collateral and option balances
    Accounts->>Derive: get_token_price(option symbol)
    Derive-->>Accounts: cached mark price
    Accounts-->>Accounts: calculate option holding value

Loading

_{Reviews (3): Last reviewed commit: "fix(test): apply derive options patch be..." | Re-trigger Greptile}