@continuumdao/ctm-mpc-defi 0.2.8 → 0.2.9

package/dist/agent/skills/hyperliquid/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: hyperliquid
+description: Hyperliquid perps, vaults, and HYPE staking via HyperEVM CoreWriter — Continuum MPC multi-sign.
+---
+
+# Hyperliquid (MCP)
+
+Hyperliquid is a perpetuals and spot exchange with on-chain actions routed through **HyperEVM CoreWriter** (`0x3333…3333`). Continuum MPC sends **single-tx CoreWriter batches** from the KeyGen executor on HyperEVM.
+
+Supported chains (must be in node chain registry with `rpcGateway`):
+
+| chainId | Network |
+|--------:|---------|
+| **999** | HyperEVM mainnet |
+| **998** | Hyperliquid testnet |
+
+The MPC **executor address** (`keyGen.ethereumaddress`) is the Hyperliquid **user account** for balances, positions, and orders.
+
+## What Hyperliquid does (explain to users)
+
+- **Perps:** USD-margined perpetuals (BTC, ETH, …) plus optional **HIP-3** builder dexes.
+- **Spot ↔ Perp:** USDC is one asset split between **spot** and **perp margin** ledgers (not separate ERC20s). Move with `usdClassTransfer`.
+- **Vaults:** Deposit/withdraw USD into protocol vaults (withdraw includes accrued PnL).
+- **Staking:** Stake/unstake **HYPE** and delegate to validators.
+
+Trading reads use Hyperliquid **REST `/info`**. Writes use **CoreWriter** on HyperEVM (not the signed `/exchange` API).
+
+## Getting started (funding)
+
+Before first trade, the user typically needs:
+
+1. **USDC on Hyperliquid** — deposit via the official Hyperliquid bridge (commonly from **Arbitrum** USDC). Funds appear in the spot/perp account tied to the MPC address.
+2. **Perp margin** — for perp orders, USDC must be in the **perp** bucket. Use `ctm_hyperliquid_fetch_usd_class_balances` then `ctm_hyperliquid_build_usd_transfer_multisign` with `toPerp: true` if spot USDC is high but perp withdrawable is low.
+3. **HYPE on HyperEVM for gas** — CoreWriter txs on chain **999** / **998** require **native HYPE** on the executor for gas. Ensure the KeyGen wallet holds enough HYPE on HyperEVM (bridge/deposit separately from USDC trading balance).
+4. **Leverage** — Hyperliquid stores a per-market leverage setting. Check `ctm_hyperliquid_fetch_open_context` (`leverageLabel`, `availableToBuy` / `availableToSell`). Changing leverage on-exchange is **not** exposed in v1 MCP (user adjusts on Hyperliquid UI if needed).
+
+Positions and orders from MCP reflect **live HyperCore state** after prior txs are **broadcast** — pending multi-sign requests are not visible until executed.
+
+## Typical agent flow (open perp)
+
+1. `load_defi_protocol({ protocolId: "hyperliquid" })`
+2. `get_defi_protocol_skill` — this file (+ shared gas/submit section appended)
+3. Confirm chain **999** or **998** in `get_chain_registry` with RPC
+4. `ctm_hyperliquid_fetch_markets({ chainId: 999 })` — pick `coin` (e.g. `BTC`); note `maxLeverage`
+5. `ctm_hyperliquid_fetch_market_snapshot({ chainId, coin, interval: "15m" })` — mid + candles
+6. `ctm_hyperliquid_fetch_open_context({ chainId, executorAddress, coin })` — account, leverage, max size
+7. `ctm_hyperliquid_fetch_usd_class_balances({ chainId, executorAddress })` — spot vs perp USD if needed
+8. `get_multi_sign_gas_options({ chainId })` — confirm `useCustomGas` with user
+9. `ctm_hyperliquid_build_limit_order_multisign` → **`{ requestId }`**
+10. Base MPC lifecycle (shared gas/submit section below)
+
+## Tool selection
+
+### Read-only
+
+| User intent | MCP tool |
+|-------------|----------|
+| List perp markets + HIP-3 dexes | `ctm_hyperliquid_fetch_markets` |
+| Mid price + OHLCV | `ctm_hyperliquid_fetch_market_snapshot` |
+| Account + capacity for one coin | `ctm_hyperliquid_fetch_open_context` |
+| Open positions | `ctm_hyperliquid_fetch_positions` |
+| Open orders | `ctm_hyperliquid_fetch_open_orders` |
+| Spot vs perp USDC | `ctm_hyperliquid_fetch_usd_class_balances` |
+| Vault catalog (+ APR) | `ctm_hyperliquid_fetch_vaults` |
+| User vault equity | `ctm_hyperliquid_fetch_user_vault_equities` |
+| HYPE stake summary | `ctm_hyperliquid_fetch_staking_summary` |
+| Validator delegations | `ctm_hyperliquid_fetch_delegations` |
+
+### Multi-sign (writes)
+
+| User intent | MCP tool |
+|-------------|----------|
+| Open / add limit or IoC order | `ctm_hyperliquid_build_limit_order_multisign` |
+| Close / reduce position | `ctm_hyperliquid_build_close_multisign` |
+| Cancel open order | `ctm_hyperliquid_build_cancel_multisign` |
+| Move USDC spot ↔ perp | `ctm_hyperliquid_build_usd_transfer_multisign` |
+| Vault deposit | `ctm_hyperliquid_build_vault_deposit_multisign` |
+| Vault withdraw | `ctm_hyperliquid_build_vault_withdraw_multisign` |
+| Stake HYPE | `ctm_hyperliquid_build_stake_multisign` |
+| Unstake HYPE | `ctm_hyperliquid_build_unstake_multisign` |
+| Delegate to validator | `ctm_hyperliquid_build_delegate_multisign` |
+| Undelegate | `ctm_hyperliquid_build_undelegate_multisign` |
+
+## Common multisign inputs (all `build_*` tools)
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `keyGen` | yes | `{ pubkeyhex, keylist?, ClientKeys? }` |
+| `chainId` | yes | **999** or **998** |
+| `rpcUrl` | yes | HyperEVM RPC from chain registry |
+| `executorAddress` | yes | MPC `ethereumaddress` |
+| `chainDetail` | yes | Gas config row from registry |
+| `purposeText` | yes | Human-readable sign request purpose |
+| `useCustomGas` | yes | See gas section below |
+| `customGasChainDetails` | no | Snapshot when `useCustomGas: true` |
+
+## Limit order example
+
+```json
+{
+  "keyGen": { "pubkeyhex": "…", "keylist": ["…"] },
+  "chainId": 999,
+  "rpcUrl": "https://…",
+  "executorAddress": "0x…",
+  "chainDetail": {},
+  "purposeText": "Hyperliquid: long BTC 0.01 @ 95000",
+  "useCustomGas": false,
+  "coin": "BTC",
+  "isBuy": true,
+  "limitPxHuman": "95000",
+  "szHuman": "0.01",
+  "tif": "gtc"
+}
+```
+
+- `tif`: `gtc` (default), `ioc`, or `alo`
+- `marketKind`: optional `perp` (default) or `spot`
+- `dex`: optional HIP-3 dex name; coin may be prefixed e.g. `xyz:SYMBOL`
+
+Validate `szHuman` against `availableToBuy` / `availableToSell` from `fetch_open_context`.
+
+## Close position example
+
+Use `isLong: true` for a **long** position (submits sell reduce-only IoC):
+
+```json
+{
+  "coin": "BTC",
+  "isLong": true,
+  "limitPxHuman": "94000",
+  "szHuman": "0.01",
+  "tif": "ioc"
+}
+```
+
+## Cancel example
+
+```json
+{
+  "coin": "BTC",
+  "oid": 123456789
+}
+```
+
+`oid` from `ctm_hyperliquid_fetch_open_orders`.
+
+## Spot ↔ Perp USD transfer
+
+```json
+{
+  "usdHuman": "100",
+  "toPerp": true
+}
+```
+
+Check balances first with `ctm_hyperliquid_fetch_usd_class_balances`.
+
+## Vault / stake
+
+- **Vault deposit/withdraw:** `vaultAddress` from `fetch_vaults`; `usdHuman` amount. Mainnet vault catalog fetch can take ~10–15s (large stats feed). Testnet catalog is empty.
+- **Stake/unstake:** `hypeHuman` amount in HYPE units.
+- **Delegate/undelegate:** `validator` address + `hypeHuman`.
+
+## HIP-3 dexes
+
+`fetch_markets` returns `dexes[]`. Pass `dex` on reads and on limit/cancel/close when trading builder-deployed perps. Coin names may include a dex prefix.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---------|----------------|
+| `availableToBuy` / `availableToSell` is 0 | No perp margin, leverage too high, or USDC still in spot — transfer to perp |
+| Order succeeds on-chain but no position | Limit not filled yet; IoC may partially/fully reject |
+| Position missing after multi-sign | Request not yet broadcast; or wrong dex filter |
+| Vault list empty on 998 | Expected — catalog is mainnet-only |
+| CoreWriter tx fails on broadcast | Insufficient **HYPE** on HyperEVM for gas |
+| Size rejected | Exceeds `availableToBuy`/`availableToSell` at current leverage |