Cobo Agentic Wallet
Back to Recipes
Hyperliquid Spot Trade

Hyperliquid Spot Trade

Execute spot token swaps on Hyperliquid L1 orderbook. Supports limit and market orders.

CategoryTradingDeFi
ChainsHYPERLIQUID
C
Cobo· Author
43 views·25 uses

Overview

Execute spot token swaps on Hyperliquid L1 orderbook. Supports limit and market orders.

Facts

•api.mainnet: https://api.hyperliquid.xyz
•api.testnet: https://api.hyperliquid-testnet.xyz
•info endpoint: POST /info — spot balances, open orders, spot metadata
•exchange endpoint: POST /exchange — place/cancel spot orders, spot transfer
•auth: EIP-712 typed-data signature (same as perp)
•spot meta: query via POST /info {"type": "spotMeta"} — returns tokens[] and universe[]
•spot asset index: spot pairs use index ≥ 10000 (e.g., HYPE/USDC = 10000; query spotMeta for exact mapping)
•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)
•order field a: spot asset index (≥10000); from spotMeta universe[i].coin
•order field s: size in base token units as string; precision from szDecimals in spotMeta
•order field p: price as USDC string; USDC has 6 decimal precision as quote asset
•cancel field o: order ID from open orders response (POST /info {"type":"openOrders"})

Typical Flows

Query spot metadata:

1.POST /info {"type": "spotMeta"} — get available spot tokens and pairs with index, name, szDecimals

Check balances:

2.POST /info {"type": "spotClearinghouseState", "user": "<address>"} — get spot token balances

Place spot order — 1 signed action:

3.POST /exchange with action order:
json
{
  "action": {
    "type": "order",
    "orders": [{
      "a": 10000,
      "b": true,
      "p": "25.50",
      "s": "10",
      "r": false,
      "t": {"limit": {"tif": "Gtc"}}
    }],
    "grouping": "na"
  },
  "nonce": <timestamp_ms>,
  "signature": "<EIP-712 sig>"
}
•a: spot asset index (≥10000; from spotMeta)
•b: true=buy (USDC→token), false=sell (token→USDC)
•p: limit price
•s: size in base token units
•t: {"limit":{"tif":"Gtc"}} for resting, {"limit":{"tif":"Ioc"}} for immediate-or-cancel (effective market order)

Cancel spot order — 1 signed action:

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

Spot transfer between sub-accounts — 1 signed action:

5.POST /exchange with action spotSend to transfer spot tokens between vault sub-accounts

Policy Controls

•Spot index ≠ perp index: Spot pairs use indices ≥10000; mixing up with perp indices (0, 1, 2, ...) places orders on wrong market.
•Liquidity varies by pair: Major pairs (HYPE, BTC, ETH) have deep books; long-tail tokens may have thin liquidity — check order book depth before large orders.
•IOC as market order: There is no explicit "market" order type for spot; use tif: "Ioc" with aggressive price to simulate market execution.
•No leverage on spot: Spot is fully collateralized; ensure sufficient USDC balance for buys or token balance for sells.
•EIP-712 signature security: Never expose private key; use signing libraries.
•Token delistings: Spot tokens can be delisted; check spotMeta for current active pairs before trading.
•Decimal precision: Each token has different szDecimals and weiDecimals; query spotMeta — incorrect precision causes order rejection.
•Not applicable for: leveraged perpetual trading — use hyperliquid-perp-trade; tokens not listed on Hyperliquid spot (verify active pairs via spotMeta before trading)
•Partial reference: use web search for unlisted spot pairs, token indices, 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.