1---2name: 1k-perps-module3description: OneKey Perps/Hyperliquid development for views/Perp, orders, orderbook, charts, Relay deposits, positions, funding, margin, and liquidation. Excludes generic Swap/Market work.4---56# Perps / Hyperliquid Domain Guide78Use this as a **Perps/Hyperliquid domain router** for order semantics, realtime subscriptions, and UI/background state races. Choose the owner and proof path; verify anchors with `rg` before editing.910## 60-Second Triage11121. **Gate**: use only when OneKey Perps/Hyperliquid is explicit in the prompt or file path.132. **Infer scope**: asset type (`perp`/`spot`), account/dex, order mode, and platform. Ask only if missing scope blocks correctness or creates trading risk.143. **Pick owner** from the matrix; avoid downstream display shims for trading/realtime contracts.154. **Load minimum refs**: one matching reference first; add [code-map.md](references/rules/code-map.md) / [validation-recipes.md](references/rules/validation-recipes.md) only for owner/proof/implementation.1617## Trigger Boundary1819| Prompt/file signal | Use this skill? | First move |20| --- | --- | --- |21| `views/Perp`, ServiceHyperLiquid, Hyperliquid, Perps/永续/合约 trading | Yes | Pick owner below, then one reference |22| Generic Market K-line, generic TradingView bridge, generic token selector | No | Use adjacent Market/TradingView/token-selector skill or repo search |23| Generic Swap Relay quote/status/pending/requestId | No | Use `$1k-trade-swap-market` unless Perps deposit is explicit |24| Perps deposit, `usePerpDeposit`, `fetchPerpDeposit*`, `perpsDepositOrderAtom`, `perp-deposit` endpoint | Yes | Open [deposit-relay.md](references/rules/deposit-relay.md) |2526If Perps/Hyperliquid is only a guess, do **not** load all references; verify the file/surface with `rg` or use the adjacent skill.2728## Owner Matrix2930| Surface | Primary owner | Usual proof |31| --- | --- | --- |32| Order submit/cancel/TWAP/scale/TIF | `ServiceHyperliquidExchange.ts`, Hyperliquid `actions.ts`, shared Perps utils/types | SDK type/source check + targeted order utility/action tests |33| L2/BBO/orderbook subscriptions | `ServiceHyperliquidSubscription.ts`, Hyperliquid context actions, freshness utils | rapid switch/reconnect + L2/BBO freshness proof |34| Deposit quote/status | `packages/kit-bg/src/services/ServiceSwap.ts`, `perpsDepositOrderAtom` | active `fromTxId`; `requestId` only when backend/Relay exposes it |35| Positions/account state/funding/margin/liquidation | `ServiceHyperliquid.ts`, Hyperliquid context atoms/actions, account-scoped Perps hooks/utils | account/dex/asset scoped proof; no stale positions/account summary |36| Perps TradingView/K-line/chart lines | `packages/kit/src/components/TradingView/TradingViewPerpsV2/TradingViewPerpsV2.tsx` | readiness/message/reconnect scenarios |37| UI-only display | Perps component/list/row files | display proof only; do not mutate trading contracts here |3839## Quick Reference4041| Topic | Guide | Start With |42| --- | --- | --- |43| Code map | [code-map.md](references/rules/code-map.md) | `views/Perp`, Hyperliquid context, BG service, shared types/utils |44| Order contracts | [order-contracts.md](references/rules/order-contracts.md) | TWAP, scale, TIF, trigger, reduce-only, precision |45| State and subscriptions | [state-subscriptions.md](references/rules/state-subscriptions.md) | account/dex/asset scoping, L2/BBO, active target, cleanup |46| Perps TradingView bridge | [tradingview-bridge.md](references/rules/tradingview-bridge.md) | `TradingViewPerpsV2`, Perps K-line readiness, chart lines |47| Relay deposit | [deposit-relay.md](references/rules/deposit-relay.md) | Perps deposit address flow, requestId tracking, pending cards |48| Positions/account state | [positions-account-state.md](references/rules/positions-account-state.md) | positions, balances, PnL/PNL/P&L, funding, margin, liquidation |49| Failure patterns | [failure-patterns.md](references/rules/failure-patterns.md) | recurring bugs and hard-to-see regressions |50| Validation recipes | [validation-recipes.md](references/rules/validation-recipes.md) | targeted tests and runtime paths |51| Review checklist | [review-checklist.md](references/rules/review-checklist.md) | PR/source checks and release risk gates |52| Source index | [source-index.md](references/rules/source-index.md) | volatile SDK/API/docs/vault lookup points |5354## Agent Routing Examples5556| User asks about | Load first | Then verify |57| --- | --- | --- |58| "TWAP cancel/list/history is wrong" | order contracts + code map | TWAP state/cancel/history recipes |59| "Scale order children/precision/TIF" | order contracts | scale utility tests + partial-failure runtime path |60| "Orderbook flashes old BTC after ETH switch" | state/subscriptions + code map | rapid asset/account switch; L2/BBO freshness |61| "Perps K-line blank after offline/reconnect" | TradingView bridge | ready-state/reconnect scenarios, native if touched |62| "Perps deposit pending/completed wrong" | Relay deposit | active tx/request scope and stale quote cases |63| "Perps positions/PnL/funding/margin/liquidation/account summary stale" | positions/account state | account/dex/asset scope; no stale position/account display |64| "Review a Perps PR" | changed-surface reference first; review checklist second | use failure patterns to challenge findings and validation gaps |6566## Output Defaults6768- Implementation: report surface, state owner, order/subscription contract touched, files changed, targeted validation, and runtime proof gaps.69- Review: lead with findings; separate correctness blockers, release blockers, and follow-up improvements.70- Research: distinguish stable module rules from volatile backend/API/business facts that must be rechecked.7172## Hard Stops7374- Do not log private keys, signatures, mnemonics, raw sensitive payloads, or user secrets while debugging Perps.75- Do not bypass enable-trading, account bind, signing, or risk validation just to make a UI submit succeed.76- Do not use production live order placement/cancel/withdraw/deposit as validation unless the user explicitly authorizes that exact action and account.77- Do not change the owner of truth through a downstream display shim; edit the owner itself.78- Do not use ticker/mid recovery as proof that orderbook, token selector, or TradingView recovered — verify each surface's own freshness/readiness.79- Do not leave old L2/BBO/orderbook/chart-line data visible after an asset/account/dex switch.80- Do not couple K-line WebView recovery to global WS recovery.81- Do not trust Relay deposit status by deposit address alone when a request/requestId scope exists.8283## Verify Against the Source8485Order semantics, TIF, TWAP, scale, trigger, and reduce-only are **volatile, SDK-versioned contract facts** — confirm them against the source, do not trust memory:8687- SDK types (type-enforced, in repo): the action method files under `node_modules/@nktkas/hyperliquid/src/api/exchange/_methods/`.88- Official docs: <https://hyperliquid.gitbook.io/hyperliquid-docs> (API → Exchange endpoint).89- Recheck on every `@nktkas/hyperliquid` bump; new fields/TIF values (e.g. `FrontendMarket`) appear over time.9091## Related Skills9293- `$1k-tradingview-communication` - TradingView message contracts and iframe bridge.94- `$1k-state-management` - Jotai atom/context conventions.95- `$1k-performance` - Render, subscription, and hot-path performance.96- `$1k-trade-swap-market` - Adjacent trade/review/history patterns; do not copy swap provider semantics blindly.97- `$1k-cross-platform` - Platform-specific RN/Web/Desktop behavior.98- `$1k-analytics` - Perps analytics/logging changes.
onekeyhq