hybrid-perps-spec

Project Overview

Background & Motivation

Platform currently relies on Hyperliquid as the underlying matching and settlement engine for perpetual futures. Platform revenue is limited to a 0.02% builder fee, resulting in a very low profit ceiling.

Core MVP Insight: Retail traders (small orders) have a statistically negative win rate. By internalizing small orders (acting as counterparty) and forwarding large orders to Hyperliquid, Platform captures retail losses while avoiding concentrated risk from large directional positions.

MVP Goals

  1. Per-order routing decisions: Order notional ≤ threshold → platform internalization; > threshold → forward to Hyperliquid
  2. Reuse all Hyperliquid data and rules: Prices, funding rates, leverage, and listed assets fully mirrored from HL
  3. Dual position system: A single user can simultaneously hold Platform-internal and HL positions
  4. Unified liquidation by Platform: All liquidation decisions are made by Platform regardless of position location
  5. Isolated and cross margin support: Cross positions share account equity; unrealized PnL from one affects liquidation of others
  6. High-fidelity HL calculation replication: Platform’s self-computed PnL, liquidation price, and funding must achieve ≥95% sync with HL

Scope

In Scope Out of Scope
Order notional routing engine Custom matching engine (Option 3, future upgrade path)
Platform B-book position management Custom price/index price system
HL proxy execution and state sync Independent market maker
Isolated/cross margin models Custom funding rates, leverage, or listed assets
Unified liquidation engine On-chain settlement contracts
Full HL calculation replication Smart contract custody of user funds
Multi-chain asset aggregation (ops layer) Options, spot, copy trading
5-minute withdrawal SLA User classification/risk profiling system
Exposure control and hedging User-to-user order matching (Maker/Taker)
— Single-order cross-threshold splitting (Phase 4 reserved)

Custom Matching Engine (Option 3) Exclusion Note: The current design is Option 2 (internal B-book + threshold-based hedging), where Platform is the sole counterparty for all INTERNAL positions. No user-to-user order matching occurs. A matching engine (including Maker/Taker mechanics, price/time priority queues, internal liquidity pools) is the future path toward Option 3 and is not in MVP scope.

MVP Implementation Phases

Phase Name Key Deliverables
Phase 1 Foundation Account system + full HL API wrapper + market data passthrough + multi-chain aggregation + withdrawal guarantee
Phase 2 Routing & Hedging MVP Order notional routing + HL fill correction + drift logging + hedge engine + net exposure monitoring + risk reserve (canary: all orders to HL initially)
Phase 3 Go Live B-book execution layer + unified liquidation + isolated/cross margin + HL calc replication + drift fallback + routing mode auto-switching + full risk dashboard
Phase 4 Optimization Routing threshold tuning + hedging strategy optimization + drift reduction + large order splitting + cross-threshold routing

Revenue Sources

Source Scenario Description
Client loss (B-book) INTERNAL positions, user loss/liquidation User loss = platform profit (core revenue)
Builder Fee Large orders forwarded to HL 0.02% per trade
Trading fee All orders Taker/maker spread
Funding rate INTERNAL position holders Mirror HL rate; platform is counterparty

Dual Position P&L Logic

Position Type Liquidated By Platform P&L
INTERNAL (B-book) Platform internal settlement Platform earns client loss
HYPERLIQUID (HL position) Platform triggers → sends close order to HL No additional client loss

Calculation Drift Risk

For HYPERLIQUID positions, Platform self-computes PnL and liquidation price. If Platform’s calculation differs from HL’s actual:

Calculation accuracy directly affects platform risk. Target sync rate: ≥95%. See 05-hl-execution.md and 09-settlement.md.