Cobo Agentic Wallet
Back to Recipes
Hyperliquid Perp Trade

Hyperliquid Perp Trade

Open perpetual positions on Hyperliquid L1 DEX. Supports market, limit, stop-market, stop-limit orders with up to 50x leverage.

CategoryTradingDeFi
ChainsHYPERLIQUID
C
Cobo· Author
354 views·15 uses

Overview

Open perpetual positions on Hyperliquid L1 DEX. Supports market, limit, stop-market, stop-limit orders with up to 50x leverage.

Facts

•api.mainnet: https://api.hyperliquid.xyz
•api.testnet: https://api.hyperliquid-testnet.xyz
•info endpoint: POST /info — account state, open orders, positions, funding history
•exchange endpoint: POST /exchange — place/cancel orders, update leverage, transfer collateral
•websocket: wss://api.hyperliquid.xyz/ws
•auth: EIP-712 typed-data signature per action (no API key; wallet signature only)
•collateral: USDC (bridged from Arbitrum to Hyperliquid L1)
•leverage: up to 50x (asset-dependent); set via updateLeverage action
•margin modes: cross-margin (default) or isolated-margin per asset
•tick size & lot size: query via POST /info {"type": "meta"} — returns universe[] with szDecimals
•funding rate: hourly funding; query via POST /info {"type": "fundingHistory"}
•eip712_domain (mainnet): {"name":"Exchange","version":"1","chainId":1337,"verifyingContract":"0x0000000000000000000000000000000000000000"}
•eip712_domain (testnet): {"name":"Exchange","version":"1","chainId":998,"verifyingContract":"0x0000000000000000000000000000000000000000"}
•nonce: current Unix timestamp in milliseconds (integer); stale nonce causes rejection
•order field s: size in base asset units as decimal string; precision from szDecimals in meta
•order tif values: "Gtc" (resting limit), "Ioc" (immediate-or-cancel), "Alo" (add-liquidity-only)

Typical Flows

Deposit collateral (bridge from Arbitrum):

1.On Arbitrum: approve(hyperliquid_bridge, amount) on USDC contract
2.Call bridge contract to deposit USDC into Hyperliquid L1 vault
3.Alternatively: use Hyperliquid web UI to bridge, then interact via API

Set leverage — 1 signed action:

1.POST /exchange with action updateLeverage:
json
{
  "action": {"type": "updateLeverage", "asset": 0, "isCross": true, "leverage": 10},
  "nonce": <timestamp_ms>,
  "signature": "<EIP-712 sig>"
}

Open position — 1 signed action:

2.POST /exchange with action order:
json
{
  "action": {
    "type": "order",
    "orders": [{
      "a": 0,
      "b": true,
      "p": "30000",
      "s": "0.1",
      "r": false,
      "t": {"limit": {"tif": "Gtc"}}
    }],
    "grouping": "na"
  },
  "nonce": <timestamp_ms>,
  "signature": "<EIP-712 sig>"
}
•a: asset index (0=BTC, 1=ETH, ...; query via /info {"type":"meta"})
•b: true=buy/long, false=sell/short
•p: price as string
•s: size as string (in base asset units)
•r: reduce-only flag
•t: order type — {"limit":{"tif":"Gtc"}}, {"limit":{"tif":"Ioc"}}, {"trigger":{"triggerPx":"...","isMarket":true,"tpsl":"sl"}}

Set TP/SL — 1 signed action each:

3.Place trigger order with tpsl: "tp" for take-profit or tpsl: "sl" for stop-loss

Close position — 1 signed action:

4.Place opposite-side order with r: true (reduce-only) or same-size market order

Cancel order — 1 signed action:

5.POST /exchange with action cancel:
json
{
  "action": {"type": "cancel", "cancels": [{"a": 0, "o": <order_id>}]},
  "nonce": <timestamp_ms>,
  "signature": "<EIP-712 sig>"
}

Withdraw (back to Arbitrum) — 1 signed action:

6.POST /exchange with action withdraw3:
json
{
  "action": {"type": "withdraw3", "hyperliquidChain": "Mainnet", "signatureChainId": "0xa4b1", "destination": "<arb_address>", "amount": "100", "time": <timestamp_ms>},
  "nonce": <timestamp_ms>,
  "signature": "<EIP-712 sig>"
}

Policy Controls

•Leverage amplifies losses: 50x leverage means 2% adverse move = 100% margin loss; always set stop-loss.
•Liquidation risk: Positions liquidate when margin ratio drops below maintenance margin; cross-margin shares collateral across all positions, isolated margin confines risk.
•EIP-712 signature security: Never expose private key; use signing libraries (ethers.js, viem).
•Funding rate cost: Hourly funding can accumulate significantly on long holds; check fundingHistory before opening positions.
•Asset index mapping: Asset indices can change; always query /info {"type":"meta"} for current universe mapping — never hardcode.
•Reduce-only flag: When closing, set r: true to prevent accidental position reversal.
•Nonce freshness: Nonce must be current timestamp in ms; stale nonce = rejected action.
•Bridge delay: Arbitrum → Hyperliquid deposits take ~1-10 min; withdrawals back to Arbitrum take ~10-30 min.
•Testnet differences: Testnet uses different API domain and may have different asset listings; do not mix configs.
•Not applicable for: spot token trading on Hyperliquid — use hyperliquid-spot-trade; trades without USDC collateral already bridged to Hyperliquid L1
•Partial reference: use web search for unlisted markets, parameters, or up-to-date API specs

References

•Docs: https://hyperliquid.gitbook.io/hyperliquid-docs/llms.txt — REST/WebSocket API, EIP-712 action signing, order types, asset indices, vault operations.