starchild-ai-agent/official-skills

hyperliquid

Trade perp futures, spot, and RWA on Hyperliquid DEX with up to asset max leverage.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/starchild-ai-agent/official-skills --skill hyperliquid

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Hyperliquid Trading

Trade perpetual futures and spot tokens on Hyperliquid, a fully on-chain decentralized exchange. Orders are signed using this agent's EVM wallet and submitted directly to the Hyperliquid L1.

Prerequisites

Before trading, the wallet policy must be active. Load the wallet-policy skill and propose the standard wildcard policy (deny key export + allow *). This covers all Hyperliquid operations — USDC deposits, EIP-712 order signing, and withdrawals.

Runtime Model: How to Call Hyperliquid (Read This First)

This skill is script-delivery. It registers no hl_* agent tools — calling hl_deposit, hl_order, or any other hl_* name as a tool will always fail with "not found in registry". That is by design, not a bug or a missing install.

There are exactly two working lanes:

Lane 1 — Read-only queries (exports.py)

python
from core.skill_tools import hyperliquid

account = hyperliquid.hl_account()
mids    = hyperliquid.hl_market()
candles = hyperliquid.hl_candles(coin="BTC", interval="1h", hours_back=24)

Any wallet, not just your own. Every user-scoped function takes an optional address. Omit it for the agent's own wallet; pass a 0x address to inspect a third party. This is what makes "analyse this wallet's Hyperliquid PnL" answerable — Hyperliquid is an off-chain order book, so a DeBank-style chain scan cannot see any of it.

python
hyperliquid.hl_portfolio(address="0x1f16...")   # PnL time series
hyperliquid.hl_account(address="0x1f16...")     # their open positions

32 functions, grouped:

GroupFunctions
Accounthl_account hl_balances hl_total_balance hl_user_role hl_user_fees hl_rate_limit hl_sub_accounts hl_referral hl_extra_agents
PnL & historyhl_portfolio hl_fills hl_fills_by_time hl_historical_orders hl_ledger hl_funding_payments hl_twap_fills hl_vault_equities
Ordershl_open_orders hl_open_orders_full hl_order_status
Markethl_market hl_orderbook hl_candles hl_funding hl_predicted_funding hl_meta hl_meta_ctxs hl_spot_meta hl_spot_meta_ctxs hl_perp_dexs
Stakinghl_staking hl_staking_delegations hl_staking_rewards

Read-only only — no writes on this lane.

Answering "what is this wallet's PnL?"

hl_portfolio returns 8 windows — day, week, month, allTime and the perp* equivalents — each with accountValueHistory and pnlHistory as [epoch_ms, value] pairs. pnlHistory restarts at 0 at the start of each window, so read allTime for lifetime PnL.

python
pf = dict(hyperliquid.hl_portfolio(address=addr))
pnl = float(pf["allTime"]["pnlHistory"][-1][1])

For a cost-basis reconstruction, combine three sources: hl_ledger (capital in/out — deposits, withdrawals, vault moves), hl_fills_by_time (realized closedPnl per fill, 2000 max per call — page by passing the last fill's time as the next start), and hl_funding_payments (funding paid/received). Check hl_user_role first: role "missing" means the address never traded here, which is not the same as "no positions".

Lane 2 — Writes: orders, cancels, transfers, deposits (client.py)

Every write goes through HyperliquidClient, which owns the EIP-712 signing pipeline. It is an async class — await every call.

python
from skills.hyperliquid.client import HyperliquidClient

client = HyperliquidClient()

# Deposit USDC to the Hyperliquid bridge (minimum 5 USDC)
res = await client.deposit_usdc(amount=500)

# Place an order
res = await client.place_order(
    coin="BTC", is_buy=True, size=0.001, price=95000, order_type="limit",
)

# Cancel / leverage / transfer / withdraw
await client.cancel_all("BTC")
await client.update_leverage(coin="BTC", leverage=5, is_cross=True)
await client.transfer_usd(amount=100, to_perp=True)
await client.withdraw_from_bridge(amount=50)

Prerequisite for Lane 2: the wallet policy must be active — load the wallet-policy skill and propose the standard wildcard policy (deny key export + allow *). That covers deposits, EIP-712 order signing, and withdrawals.

Naming note: the rest of this document refers to operations by their historical hl_* names (e.g. "hl_deposit"). Those are labels for the operation, not callable tools — always reach them via Lane 1 or Lane 2 above.

Available Tools

Account & Market Info

ToolWhat it does
hl_total_balanceCheck how much you can trade with (use this for balance checks!)
hl_accountOpen positions and unrealized PnL
hl_balancesToken holdings (USDC, HYPE, etc.)
hl_portfolioPnL and account value over time — day/week/month/allTime
hl_ledgerDeposits, withdrawals, transfers — the capital in/out record
hl_fills_by_timeFills within a date range, for cost-basis work
hl_marketGet current prices for crypto or stocks
hl_meta_ctxsMarket-wide scan: markPx, funding, OI, volume per asset
hl_orderbookCheck order book depth and liquidity
hl_fillsSee recent trade fills and execution prices
hl_candlesGet price charts (1m, 5m, 1h, 4h, 1d)
hl_fundingCheck funding rates for perps
hl_open_ordersSee pending orders
hl_open_orders_fullPending orders with stop-loss / take-profit detail

All of the above accept address="0x..." to inspect any wallet, not just the agent's own.

Trading

ToolWhat it does
hl_orderBuy or sell perps (crypto/stocks)
hl_spot_orderBuy or sell spot tokens
hl_tpsl_orderPlace stop loss or take profit orders
hl_leverageSet leverage (1x to asset max)
hl_cancelCancel a specific order
hl_cancel_allCancel all open orders
hl_modifyChange order price or size

Funds

ToolWhat it does
hl_depositAdd USDC from Arbitrum (min $5)
hl_withdrawSend USDC to Arbitrum (1 USDC fee, ~5 min)
hl_transfer_usdMove USDC between spot/perp (rarely needed)

Platform

ToolWhat it does
hl_approve_builderApprove Starchild builder fee collection (auto-done on first order)
hl_builder_statusCheck builder approval status and collected rewards

Quick Start

Just tell the agent what you want to trade - it handles everything automatically.

Examples:

User: "Buy $20 of Bitcoin with 5x leverage"
Agent: [checks balance → sets leverage → places order → reports fill]
Result: "✓ Bought 0.0002 BTC at $95,432 with 5x leverage. Position opened."

User: "Long NVIDIA with $50, 10x"
Agent: [auto-detects NVIDIA = xyz:NVDA → executes → verifies]
Result: "✓ Bought 0.25 NVDA at $198.50 with 10x leverage. Filled at $198.62."

User: "Sell my ETH position"
Agent: [checks position size → closes → reports PnL]
Result: "✓ Sold 0.5 ETH at $3,421. Realized PnL: +$12.50"

You don't need to:

  • Understand account modes or fund transfers
  • Check balances manually (agent does it)
  • Calculate position sizes (agent does it)
  • Verify fills (agent does it)

Just say what you want, the agent handles the rest.


Agent Behavior Guidelines

🤖 As the agent, you should ALWAYS do these automatically (never ask the user):

  1. Check available funds - Use hl_total_balance before EVERY trade to see total available margin
  2. Detect asset type - Recognize if user wants crypto (BTC, ETH, SOL) or stocks/RWA (NVIDIA→xyz:NVDA, TESLA→xyz:TSLA)
  3. Set leverage - Always call hl_leverage before placing orders (unless user specifies not to)
  4. Verify fills - After placing ANY order, immediately call hl_fills to check if it filled
  5. Report results - Tell user the outcome: filled price, size, and any PnL
  6. Suggest risk management - For leveraged positions, remind users about stop losses or offer to set them

🎯 User just says: "buy X" or "sell Y" or "long Z with $N"

🔧 You figure out:

  • Current balance (hltotalbalance)
  • Asset resolution (crypto vs RWA)
  • Leverage settings (hl_leverage)
  • Order sizing (calculate from user's $ amount or size)
  • Execution (hl_order)
  • Verification (hl_fills)
  • Final report to user

📊 Balance checking hierarchy:

  • ✅ Use hl_total_balance - shows ACTUAL available margin regardless of account mode
  • ❌ Don't use hl_account for balance - may show $0 even if funds available
  • ❌ Don't use hl_balances for margin - only shows spot tokens

🚀 Be proactive, not reactive:

  • Don't wait for user to ask "did it fill?" - check automatically
  • Don't ask "should I check your balance?" - just do it
  • Don't explain account modes - user doesn't care, just execute

Tool Usage Examples

Check Account State

hl_account()              # Default crypto perps account
hl_account(dex="xyz")     # Builder dex (RWA/stock perps) account

Returns marginSummary (accountValue, totalMarginUsed, withdrawable) and assetPositions array with each position's coin, szi (signed size), entryPx, unrealizedPnl, leverage.

Important: Builder perps (xyz:NVDA, xyz:TSLA, etc.) have separate clearinghouses. Always check the correct dex when trading RWA/stock perps.

Check Spot Balances

hl_balances()

Returns balances array with coin, hold, total for USDC and all spot tokens.

Check Market Prices

hl_market()                  # All mid prices
hl_market(coin="BTC")        # BTC price + metadata (maxLeverage, szDecimals)

Side Parameter Convention (read this first)

All order tools (hl_order, hl_spot_order, hl_tpsl_order, hl_modify) use the same side parameter. Use `"buy"` or `"sell"` — these are the documented values and should be your default.

For safety, the tools also accept these aliases so a model guess doesn't reverse direction on a leveraged order:

  • Buy family: "buy", "B", "bid", "long", "L", 1, true
  • Sell family: "sell", "S", "A", "ask", "short", 0, false

An unrecognized value will fail the call with a clear error — the tool never defaults to sell (or buy) when side is ambiguous. This is intentional: silently reversing direction on a leveraged position is the worst failure mode.

Note: Hyperliquid's L1 wire protocol uses "B" and "A" internally, but the tool interface here is buy/sell. Stick to buy/sell in your calls and you will never be surprised.

Place a Perp Limit Order

hl_order(coin="BTC", side="buy", size=0.01, price=95000)

Places a GTC limit buy for 0.01 BTC at $95,000.

Place a Perp Market Order

hl_order(coin="ETH", side="sell", size=0.1)

Omitting price submits an IoC order at mid price +/- 3% slippage.

Parameter format behavior:

  • Preferred: pass correct JSON types (size as number, reduce_only as boolean)
  • Hyperliquid tools now include tolerant coercion for common LLM formatting mistakes:
  • numeric strings like "0.01" → 0.01
  • boolean strings like "true"/"false" → true/false
  • integer strings like "5"/"5.0" → 5
  • Invalid/empty/non-finite values still fail with explicit validation errors

Place a Post-Only Order

hl_order(coin="BTC", side="buy", size=0.01, price=94000, order_type="alo")

ALO (Add Liquidity Only) = post-only. Rejected if it would immediately fill.

Practical guardrail for bots: If your ALO price is too close to mid (often within ~0.1% on liquid pairs), Hyperliquid may reject it. For market-making/grid bots, compute current mid first and skip or shift levels that sit inside your no-cross buffer zone.

Place a Stop Loss Order

hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl")

Automatically sells 0.01 BTC if the price drops to $90,000. Executes as market order when triggered.

For a limit order when triggered (instead of market):

hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl", is_market=false, limit_px=89900)

Place a Take Profit Order

hl_tpsl_order(coin="ETH", side="sell", size=0.5, trigger_px=3500, tpsl="tp")

Automatically sells 0.5 ETH if the price rises to $3,500. Executes as market order when triggered.

Close a Perp Position

hl_order(coin="BTC", side="sell", size=0.01, reduce_only=true)

Use reduce_only=true to ensure it only closes, never opens a new position.

Place a Spot Order

hl_spot_order(coin="HYPE", side="buy", size=10, price=25.0)

Spot orders use the same interface — just specify the token name.

Cancel an Order

hl_cancel(coin="BTC", order_id=12345678)

Get order_id from hl_open_orders.

Cancel All Orders

hl_cancel_all()              # Cancel everything
hl_cancel_all(coin="BTC")    # Cancel only BTC orders

Modify an Order

hl_modify(order_id=12345678, coin="BTC", side="buy", size=0.02, price=94500)

Set Leverage

hl_leverage(coin="BTC", leverage=10)               # 10x cross margin
hl_leverage(coin="ETH", leverage=5, cross=false)    # 5x isolated margin

Transfer USDC (rarely needed)

hl_transfer_usd(amount=1000, to_perp=true)     # Spot → Perp
hl_transfer_usd(amount=500, to_perp=false)      # Perp → Spot

Note: Usually not needed - funds are automatically shared. Only use if you get an error saying you need to transfer.

Withdraw USDC to Arbitrum

hl_withdraw(amount=100)                              # Withdraw to own wallet
hl_withdraw(amount=50, destination="0xABC...")        # Withdraw to specific address

Fee: 1 USDC deducted by Hyperliquid. Processing takes ~5 minutes.

Deposit USDC from Arbitrum

hl_deposit(amount=500)

Sends USDC from the agent's Arbitrum wallet to the Hyperliquid bridge contract. Minimum deposit: 5 USDC. Requires USDC balance on Arbitrum.

Get Candles

hl_candles(coin="BTC", interval="1h", lookback=48)

Intervals: 1m, 5m, 15m, 1h, 4h, 1d. Lookback in hours.

Check Funding Rates

hl_funding()                 # All predicted fundings
hl_funding(coin="BTC")       # BTC predicted + 24h history

Get Recent Fills

hl_fills(limit=10)

Coin vs RWA Resolution

When a user asks to trade a ticker, you need to determine whether it's a native crypto perp (use plain name) or an RWA/stock perp (use xyz:TICKER prefix).

Decision Workflow

  1. Known crypto → use plain name: "BTC", "ETH", "SOL", "DOGE", "HYPE", etc.
  2. Known stock/commodity/forex → use xyz: prefix: "xyz:NVDA", "xyz:TSLA", "xyz:GOLD", etc.
  3. Unsure → resolve with tool calls:
  • First try hl_market(coin="X") — if it returns a price, it's a crypto perp
  • If not found, try hl_market(dex="xyz") to list all RWA markets and search the results
  • Use whichever returns a match

Common RWA Categories (all use xyz: prefix)

CategoryExamples
US Stocksxyz:NVDA, xyz:TSLA, xyz:AAPL, xyz:MSFT, xyz:AMZN, xyz:GOOG, xyz:META, xyz:TSM
Commodities — Metalsxyz:GOLD, xyz:SILVER, xyz:COPPER, xyz:PLATINUM, xyz:PALLADIUM, xyz:ALUMINIUM
Commodities — Energyxyz:CL (WTI), xyz:BRENTOIL, xyz:NATGAS, xyz:TTF (EU Gas)
Commodities — Agriculturexyz:CORN, xyz:WHEAT
Commodities — Otherxyz:URANIUM
Indicesxyz:SPY
Forexxyz:EUR, xyz:GBP, xyz:JPY
If a user says "buy NVDA" or "trade GOLD", use xyz:NVDA / xyz:GOLD. These are real-world assets, not crypto.

⚠️ HIP-3 Commodity Price Lookup

All 13 commodity markets are HIP-3 builder-deployed perps. Their symbols use the xyz: prefix (e.g. xyz:GOLD, xyz:CL), NOT standard formats like XAU, XAG, or WTI.

Full commodity list: GOLD, SILVER, COPPER, PLATINUM, PALLADIUM, ALUMINIUM, CL (WTI crude), BRENTOIL, NATGAS, TTF (EU gas), CORN, WHEAT, URANIUM.

Key gotcha: HIP-3 assets are NOT included in `allMids` (the standard price feed). This means:

  • hl_market(coin="xyz:GOLD") may return no price or fail to find the asset
  • hl_market(dex="xyz") lists all builder markets but may not include mid prices

The reliable way to get commodity prices is `hl_candles`:

# Get latest gold price (use 1h candles, lookback=24 for 24h data)
hl_candles(coin="xyz:GOLD", interval="1h", lookback=24)

# Get latest copper price
hl_candles(coin="xyz:COPPER", interval="1h", lookback=24)

# Get latest silver price
hl_candles(coin="xyz:SILVER", interval="1h", lookback=24)

The close field of the most recent candle = current price. The oldest candle's open vs latest close gives 24h change.

Prefixed Name — Same Tools

All existing tools work with xyz:TICKER — just pass the prefixed coin name:

hl_market(coin="xyz:NVDA")                                    # Check NVIDIA stock perp price
hl_market(dex="xyz")                                           # List ALL available RWA/stock perps
hl_orderbook(coin="xyz:NVDA")                                 # Check liquidity
hl_leverage(coin="xyz:NVDA", leverage=3)                      # Set leverage (auto-isolated)
hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)    # Limit buy 0.5 NVDA
hl_order(coin="xyz:TSM", side="buy", size=1)                  # Market buy 1 TSM
hl_cancel(coin="xyz:NVDA", order_id=12345678)                 # Cancel order

Example: User Says "Buy NVIDIA"

  1. Recognize NVIDIA = stock → use xyz:NVDA
  2. hl_market(coin="xyz:NVDA") — Check current price, leverage limits
  3. hl_leverage(coin="xyz:NVDA", leverage=3) — Set leverage (builder perps use isolated margin)
  4. hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188) — Place limit buy
  5. hl_fills() — Check if filled

Notes

  • Builder perps (HIP-3) use isolated margin only — hl_leverage handles this automatically
  • The dex prefix (e.g. xyz) identifies which builder deployed the perp
  • All tools (candles, orderbook, funding, etc.) work the same way with prefixed names

Common Workflows

Query Commodity Prices

User: "What's the gold price?" or "Show me commodity prices" or "Oil price?"

Name → Symbol mapping:

  • Metals: GOLD→xyz:GOLD, SILVER→xyz:SILVER, COPPER→xyz:COPPER, PLATINUM→xyz:PLATINUM, PALLADIUM→xyz:PALLADIUM, ALUMINIUM→xyz:ALUMINIUM
  • Energy: WTI/Crude Oil→xyz:CL, Brent→xyz:BRENTOIL, Natural Gas→xyz:NATGAS, EU Gas→xyz:TTF
  • Agriculture: Corn→xyz:CORN, Wheat→xyz:WHEAT
  • Other: Uranium→xyz:URANIUM

Steps:

  1. Map commodity name → HIP-3 symbol using the table above
  2. hl_candles(coin="xyz:GOLD", interval="1h", lookback=24) — Get 24h of hourly candles
  3. Current price = last candle's close
  4. 24h change = (last_close - first_open) / first_open * 100
  5. Repeat for each commodity as needed

Do NOT use `hl_market()` for commodities — HIP-3 assets are not in allMids. Always use hl_candles.

Liquidity note: CL (WTI) and BRENTOIL have the highest volume. ALUMINIUM, URANIUM, CORN, WHEAT, TTF may have zero or very low liquidity — warn the user before trading these.

Trade Crypto Perps (BTC, ETH, SOL, etc.)

User: "Buy BTC" or "Long ETH with 5x"

Agent workflow:

  1. hl_total_balance() → Check available funds
  2. hl_leverage(coin="BTC", leverage=5) → Set leverage
  3. hl_order(...) → Place order
  4. hl_fills() → Verify fill and report result

Trade Stocks/RWA (NVIDIA, TESLA, GOLD, etc.)

User: "Buy NVIDIA" or "Short TESLA"

Agent workflow:

  1. Detect asset type → Convert "NVIDIA" to "xyz:NVDA"
  2. hl_total_balance() → Check available funds
  3. hl_leverage(coin="xyz:NVDA", leverage=10) → Set leverage
  4. hl_order(coin="xyz:NVDA", ...) → Place order
  5. hl_fills() → Verify fill and report result

Close Positions

User: "Close my BTC position"

Agent workflow:

  1. hl_account() → Get current position size
  2. hl_order(coin="BTC", side="sell", size=X, reduce_only=true) → Close position
  3. hl_fills() → Report PnL

Grid / Market-Making Bot Loop (service mode)

For always-on bots running inside FastAPI/worker services:

  1. Read open orders via get_open_orders(address)
  2. Read fills via get_user_fills(address)
  3. Use fills as source of truth for "order executed" events
  4. On fill:
  • buy fill → place paired sell at next grid level
  • sell fill → place paired buy at previous grid level
  1. Keep periodic reconciliation: local state vs exchange open orders

Important: Do not treat "order disappeared from open orders" as guaranteed fill. It can also mean cancel/reject/expired. Always confirm with get_user_fills (or get_order_status when needed).

Spot Trading

User: "Buy 100 HYPE tokens"

Agent workflow:

  1. hl_total_balance() → Check available USDC
  2. hl_spot_order(coin="HYPE", side="buy", size=100) → Buy tokens
  3. hl_balances() → Verify purchase

Deposit/Withdraw Funds

Deposit: User: "Deposit $500 USDC to Hyperliquid" Agent: hl_deposit(amount=500) → Done

Withdraw: User: "Withdraw $100 to my Arbitrum wallet" Agent: hl_withdraw(amount=100) → Done (5 min, 1 USDC fee)


Order Types

TypeParameterBehavior
Limit (GTC)order_type="limit"Rests on book until filled or cancelled
Market (IoC)omit priceImmediate-or-Cancel at mid +/- 3% slippage
Post-Only (ALO)order_type="alo"Rejected if it would cross the spread
Fill-or-Killorder_type="ioc" + explicit priceFill immediately at price or cancel
Stop Losshl_tpsl_order with tpsl="sl"Triggers when price drops to limit losses
Take Profithl_tpsl_order with tpsl="tp"Triggers when price rises to lock gains

Stop Loss & Take Profit Orders

Stop loss and take profit orders are trigger orders that automatically execute when the market reaches a specified price level. Use these to manage risk and lock in profits without monitoring positions 24/7.

How They Work

  1. Order Placement: Place a dormant trigger order with a trigger price
  2. Monitoring: Order sits inactive, watching the market price
  3. Trigger: When market price reaches trigger_px, order activates
  4. Execution: Order executes immediately (as market or limit order)

Stop Loss (SL)

Use case: Limit losses on a position by automatically exiting if price moves against you.

Example: You're long BTC at $95,000 and want to exit if it drops below $90,000.

hl_tpsl_order(coin="BTC", side="sell", size=0.1, trigger_px=90000, tpsl="sl")
  • trigger_px=90000: Activates when BTC drops to $90k
  • side="sell": Closes your long position
  • tpsl="sl": Marks this as a stop loss order
  • Default: Executes as market order when triggered (instant exit)

Take Profit (TP)

Use case: Lock in gains by automatically exiting when price reaches your profit target.

Example: You're long ETH at $3,000 and want to take profit at $3,500.

hl_tpsl_order(coin="ETH", side="sell", size=1.0, trigger_px=3500, tpsl="tp")
  • trigger_px=3500: Activates when ETH rises to $3,500
  • side="sell": Closes your long position
  • tpsl="tp": Marks this as a take profit order
  • Default: Executes as market order when triggered (instant exit)

Market vs Limit Execution

By default, TP/SL orders execute as market orders when triggered (instant fill, possible slippage).

For more control, use a limit order when triggered:

hl_tpsl_order(
    coin="BTC",
    side="sell",
    size=0.1,
    trigger_px=90000,
    tpsl="sl",
    is_market=false,
    limit_px=89900
)
  • trigger_px=90000: Activates at $90k
  • is_market=false: Use limit order (not market)
  • limit_px=89900: Limit price when triggered ($89,900)

Trade-off: Limit orders avoid slippage but may not fill in fast-moving markets.

Short Positions

For short positions, reverse the side parameter:

Stop loss on short (exit if price rises):

hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=98000, tpsl="sl")

Take profit on short (exit if price drops):

hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=92000, tpsl="tp")

Best Practices

  1. Always use `reduce_only=true` (default) - ensures TP/SL only closes positions, never opens new ones
  2. Match size to position - TP/SL size should equal or be less than your position size
  3. Set both TP and SL - protect both upside (take profit) and downside (stop loss)
  4. Account for volatility - don't set stops too tight or they'll trigger on normal price swings
  5. Check open orders - use hl_open_orders to verify TP/SL orders are active

Common Mistakes

MistakeProblemSolution
Wrong sideSL buys instead of sellsLong position → side="sell" for SL/TP
Size too largeTP/SL opens new positionSet size ≤ position size, use reduce_only=true
Trigger = limitConfusion about pricestrigger_px = when to activate, limit_px = execution price
No SL on leverageLiquidation riskAlways set stop loss on leveraged positions

Perps vs Spot

AspectPerpsSpot
Toolhl_orderhl_spot_order
LeverageYes (up to asset max)No
FundingPaid/received every hourNone
Short sellingYes (native)Must own tokens to sell
Check positionshl_accounthl_balances

Risk Management

  • Always check account state before trading — know your margin usage and existing positions
  • Set leverage explicitly before opening new positions (default may vary)
  • Use reduce_only when closing to avoid accidentally opening the opposite direction
  • Monitor funding rates — high positive funding means longs are expensive to hold
  • Start with small sizes — Hyperliquid has minimum order sizes per asset (check szDecimals)
  • Post-only (ALO) orders save on fees (maker vs taker rates)
  • Check fills after market orders — IoC orders may partially fill or not fill at all

Builder Code (Platform Fee)

Starchild automatically collects a 2 bps (0.02%) builder fee on every perp and spot order placed through this skill. This fee supports platform operations and is separate from Hyperliquid's own trading fees.

How it works:

  • The first time a user places an order, the skill auto-approves the Starchild builder address via the ApproveBuilderFee action (signed by the user's main wallet)
  • All subsequent orders include a builder parameter: {"b": "0x2c5320F40305fFC933385c6DCec5493fbA7b98b8", "f": 20} (20 tenths-of-bps = 2 bps)
  • The fee is collected in the quote/collateral asset (USDC) and accumulates in the builder's referral rewards
  • Users can revoke approval at any time on app.hyperliquid.xyz

Tools:

  • hl_approve_builder — Manually approve the Starchild builder (normally auto-done on first order)
  • hl_builder_status — Check approval status and view unclaimed builder rewards

If builder approval fails: Orders still go through without the builder parameter. The error is logged but does not block trading.


Common Errors

ErrorFix
"Unknown perp asset"Check coin name. Crypto: "BTC", "ETH". Stocks: "xyz:NVDA", "xyz:TSLA"
"Insufficient margin"Use hl_total_balance to check funds. Reduce size or add more USDC
"Order must have minimum value of $10"Increase size. Formula: size × price ≥ $10
"Size too small"BTC min is typically 0.001. Check asset's szDecimals
"Order would cross"ALO order rejected. Use regular limit order instead
"User or wallet does not exist"Deposit USDC first with hl_deposit(amount=500)
"Minimum deposit is 5 USDC"Hyperliquid requires at least $5 per deposit
"Policy violation"Load wallet-policy skill and propose wildcard policy
"Action disabled when unified account is active"Transfers blocked in unified mode (default). Just place orders directly
"'side' must be one of: buy/sell ..."You passed an unrecognized direction. Use "buy" or "sell". See Side Parameter Convention above
同じリポジトリから

関連する Skills

すべての Skills