Skip to content

feat(hyperliquid): add leverage, margin, liquidation, and PnL prisms with tests#623

Open
helmutkocksmann wants to merge 1 commit into
Spectral-Finance:mainfrom
helmutkocksmann:docs/issue-82-hyperliquid-perps
Open

feat(hyperliquid): add leverage, margin, liquidation, and PnL prisms with tests#623
helmutkocksmann wants to merge 1 commit into
Spectral-Finance:mainfrom
helmutkocksmann:docs/issue-82-hyperliquid-perps

Conversation

@helmutkocksmann
Copy link
Copy Markdown

Changes

Adds missing perpetual trading features for the Hyperliquid integration (issue #82):

New Prisms

  • HyperliquidSetLeveragePrism — Set leverage (1-50x) with cross/isolated margin support and vault address option
  • HyperliquidMarginManagementPrism — Add or remove margin from isolated positions
  • HyperliquidLiquidationMonitorPrism — Monitor liquidation proximity with configurable warning (20%) and critical (10%) thresholds, per-position risk levels (safe/warning/critical), and summary counts
  • HyperliquidPnLTrackerPrism — Track unrealized PnL, margin utilization, and portfolio ROI across all positions

New Beam

  • PositionManagementBeam — Orchestrates liquidation monitoring and PnL tracking, returning overall risk status (healthy/warning/critical)

New Tests (10 test suites)

All Hyperliquid prisms previously had zero test coverage. This PR adds:

  • Unit tests for all 6 existing prisms (execute_order, cancel_order, open_orders, token_info, user_state, risk_assessment)
  • Unit tests for all 4 new prisms (set_leverage, margin_management, liquidation_monitor, pnl_tracker)
  • Liquidation monitor tests include pure-function risk classification and distance-to-liquidation calculation tests
  • Integration test for the full trading workflow

Documentation

  • Livebook guide (hyperliquid_perps.livemd) covering all prisms, beams, configuration, usage examples, and risk management best practices

Acceptance Criteria Coverage

  • Order placement and management (existing prisms)
  • Position tracking system (user_state + PnL tracker)
  • Risk management implementation (risk_assessment + liquidation_monitor)
  • Liquidation monitoring (liquidation_monitor with configurable thresholds)
  • Margin management system (margin_management prism)
  • Documentation and examples (livebook guide)
  • Integration tests for trading operations
  • Risk control verification (schema tests + classification tests)

Closes #82

…with tests

Add missing perpetual trading features for Hyperliquid integration (issue Spectral-Finance#82):

New Prisms:
- HyperliquidSetLeveragePrism: Set leverage (1-50x) with cross/isolated margin
- HyperliquidMarginManagementPrism: Add/remove margin from positions
- HyperliquidLiquidationMonitorPrism: Monitor liquidation proximity with
  configurable warning/critical thresholds and per-position risk levels
- HyperliquidPnLTrackerPrism: Track unrealized PnL, funding costs, and
  portfolio ROI across all positions

New Beam:
- PositionManagementBeam: Orchestrates liquidation monitoring and PnL
  tracking with overall risk status (healthy/warning/critical)

New Tests (10 schema validation test suites for ALL Hyperliquid prisms):
- Unit tests for all 6 existing prisms (previously had zero coverage)
- Unit tests for all 4 new prisms
- Integration test for the full trading workflow
- Liquidation monitor tests include pure-function risk classification
  and distance calculation tests

Documentation:
- Livebook guide (hyperliquid_perps.livemd) covering all prisms, beams,
  configuration, usage examples, and risk management best practices

Acceptance criteria coverage:
- [x] Order placement and management (existing prisms)
- [x] Position tracking system (user_state + PnL tracker)
- [x] Risk management implementation (risk_assessment + liquidation_monitor)
- [x] Liquidation monitoring (liquidation_monitor with thresholds)
- [x] Margin management system (margin_management prism)
- [x] Documentation and examples (livebook guide)
- [x] Integration tests for trading operations
- [x] Risk control verification (schema tests + classification tests)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hyperliquid Integration and Perpetual Trading $900

1 participant