hyperliquid-perps
Hyperliquid Perps & Spot
Playbook for trading perpetuals and spot on Hyperliquid through OpenFinance, plus the real-time WebSocket for market data.
Prerequisite
- User completed
openfinance-setup(API key + EVM wallet delegation). - For trading: USDC in the user's wallet, then deposit USDC into the
Hyperliquid account via
GET /agent/trading/deposit-address(send USDC to that deposit address; chain routing is handled automatically). - For perp orders specifically: margin must be in the perp account, not
spot. Transfer with
POST /agent/trading/transfer.
Accounts & funding
GET /agent/trading/account— Perpetual account summary. ReturnsmarginSummary(accountValue, totalMarginUsed, totalNtlPos, totalRawUsd, withdrawable) and a list of open positions withentryPx,positionValue,
More from openfinance-tech/skills
openfin-polymarket
Polymarket — research, pricing, trading, deposit/withdraw, and trader leaderboard via the OpenFinance backend. Use for ANY Polymarket task. Polymarket runs a per-EOA "deposit wallet" smart contract that holds pUSD and is the on-chain `maker` on every order — pUSD on the EOA is stranded for trading, and `/user/:address/*` lookups must use the deposit-wallet address (NOT the EOA). Always call `GET /agent/polymarket/deposit-wallet` first to resolve the right address. Triggers: events / markets / odds in politics / sports (IPL, FIFA, NBA, NFL, F1, UFC, cricket) / crypto / culture / entertainment, place / cancel orders (limit GTC/GTD, market FOK/FAK, batch), neg-risk multi-outcome markets, tick sizes, builder attribution, "where do I deposit on Polymarket / what's my Polymarket address", "withdraw / cash out from Polymarket to {chain}", "Polymarket leaderboard / top traders / best wallets / who's making money / where do I rank". Covers /agent/polymarket/* (events, markets, search, orderbook, price(s), spread, last-trade-price, trades, market/:id/{open-interest,volume,liquidity,trades}, user/:address/{positions,trades,portfolio,pnl}, leaderboard, deposit-wallet, deposit-wallet/withdraw-and-bridge, order, order/market, orders, order/:id, order/:id/scoring, builder/*). For leaderboard queries — DO NOT web-fetch; this tool has the data. Prerequisite: openfin-setup.
36openfin-relay
Cross-chain bridging, swapping, and bridge+call via Relay through the OpenFinance backend. Use whenever the user wants to move tokens across chains, swap with a token change, or run a destination-chain tx funded from another chain. `recipient` may be the caller's own wallet OR any external address — Relay treats them the same. For SAME-chain transfer with NO token change (e.g. send USDC on Base to a friend's Base address), prefer `openfin-onchain` POST /agent/onchain/send — single ERC-20/SPL transfer, faster + cheaper than a bridge. Triggers: "bridge X from Y to Z", "move USDC to Base / Arbitrum / Optimism / Polygon / Solana", "swap ETH for USDC on Base", "cross-chain swap", "bridge and call", "how do I get to / back from Solana", "my USDC is stuck on Solana", "send USDC to 0x… on another chain", EVM↔EVM, EVM↔Solana, Bitcoin bridge, gas topup, native-token sentinel `0x0`, intent status. Covers POST /agent/relay/quote, POST /agent/relay/execute, GET /agent/relay/status. Includes the chainId cheatsheet (1/137/8453/10/42161/… and Solana 792703809), tradeType (EXACT_INPUT / EXACT_OUTPUT / EXPECTED_OUTPUT), why topupGas auto-disables on Solana routes, bridge+call (`txs` array). Pair with openfin-setup (API key) and openfin-troubleshooting (Blockhash not found, Custom:101, 412 setup-incomplete on Solana origin).
34openfin-setup
Auth check for the OpenFinance backend — confirms an API key is available before any other OpenFinance skill runs. Use FIRST whenever the user is about to call any /agent/* route (Polymarket, Hyperliquid, Relay), is hitting 401/412, or hasn't traded yet in this session. Triggers on "how do I get started", "API key is required", "Invalid API key", "401/412 from /agent/*", "set up OpenFinance", or any first call into a trading skill. Resolves the key from `OPENFINANCE_API_KEY` (or equivalent env / user-supplied value), confirms the format (`open_…`), verifies via GET /agent/wallets, and otherwise points the user to https://openfinance.tech to issue one.
32openfin-hyperliquid
Hyperliquid perps + spot trading via the OpenFinance backend. Use for any Hyperliquid task — orders (perp, spot, TWAP, HIP-3 stocks/commodities/FX/preipo, HIP-4 binary outcomes), leverage/margin, account balance, market data (REST + WebSocket), OHLCV candles, deposits/withdrawals. Hyperliquid is its **own L1**, not a chain variant of Arbitrum — Arbitrum is just where the deposit address lives. Fund path: USDC on Arbitrum → `GET /agent/trading/deposit-address` → L1 validators credit the HL account. Exit path: withdraw_to_arbitrum burns HL USDC, validators co-sign payout to the same EOA on Arbitrum (~5 min, $1 fee). Hyperliquid accepts **only USDC** (not USDT, not USDC.e). INR funding route: Onramp.money INR → USDC on Polygon/BSC → Relay bridge → Arbitrum → deposit. Hyperliquid runs **unifiedAccount** so spot+perp USDC share one margin pool — agents MUST sum `account.withdrawable + spot.USDC.total` and present it as ONE figure (NEVER "Perp withdrawable: $0" or "Spot USDC" as separate lines). On first balance read, if `account.withdrawable > 0` and `GET /agent/trading/abstraction` returns `"default"` or `"disabled"`, POST `{abstraction: "u"}` to upgrade (one-shot, idempotent). Triggers: "buy/long/short/sell BTC/ETH/SOL/NVDA/TSLA/...", "perp/spot order", "Gtc/Ioc/Alo/FrontendMarket", "TP/SL", "TWAP", "leverage/cross/isolated", "deposit/withdraw to Hyperliquid/Arbitrum", "HL balance", "HIP-3", "HIP-4", "outcome / split / merge / negate", "Yes/No shares", "HLP". Covers /agent/trading/* (market/{mids,metas,perp-metas,perp-categories,spot-metas,l2-book,token,all-dexs-asset-ctxs,outcome-meta}, deposit-address, account, account/spot, portfolio, rate-limit, orders, orders/details, orders/history, orders/:oid/status, twap, twap/fills, twap/:id, fills, fills/by-time, funding, leverage, margin, withdraw, abstraction, outcome/{split,merge,merge-question,negate}). Prerequisite: openfin-setup.
32openfin-troubleshooting
Error → fix lookup for the OpenFinance backend (Polymarket, Relay, Hyperliquid, Solana RPC, account-setup). Use the moment a call fails or returns an unexpected status. Triggers on the error signatures verbatim or paraphrased — Polymarket: "maker address not allowed", "balance: 0 / allowance: 0" after deposit-wallet migration, "allowance max but CLOB returns 0", "tick size", "order size below minimum"; Relay: "InstructionFallbackNotFound / Custom:101", "Blockhash not found", "401 No valid authorization signatures" or 412 on Solana execute, "User has no Solana wallet provisioned", "topupGas forced off"; Hyperliquid: "Insufficient margin / account value too low", "withdrawal not arriving on Arbitrum", WebSocket stale data, "price out of bounds". Read this BEFORE assuming a bug.
31openfin-onchain
Multi-chain on-chain token data + same-chain transfers. Read side (Uniblock-backed, 100+ chains): token metadata, wallet portfolios, balances, USD prices. Write side: same-chain transfer of any token (native, ERC-20, SOL, SPL) to any address from the caller's embedded wallet. Triggers: "what is token 0x…", "wallet portfolio", "USDC balance on {chain}", "price of {token}", "send X to Y on {chain}", "transfer USDC to wallet 0x…", "send SOL to friend's address", "pay 50 USDC". Routing rule: SAME-chain transfer → POST /agent/onchain/send (faster, cheaper); CROSS-chain or swap-and-send → openfin-relay. Covers GET /agent/onchain/token/{metadata,portfolio,balances,price} + POST /agent/onchain/send. Each call requires `x-api-key: open_…`. Prerequisite: openfin-setup.
23