hyperliquid-trade

Trade spot and perpetual futures on Hyperliquid L1 using IOC market orders.

When to Use

• Spot: buy or sell any token listed on Hyperliquid spot markets
• Perps: open long/short or close perpetual futures positions
• Balance: check spot token balances or perp positions and margin

External Communications

This skill connects to the Hyperliquid API (

api_url

hyperliquid.yaml

https://api.hyperliquid.xyz

npm install

Environment & Security Declaration

Required config files

~/.aurehub/.wdk_vault

~/.aurehub/.wdk_password

~/.aurehub/hyperliquid.yaml

Security safeguards

• Private key is decrypted from vault in memory only, never stored
• Decrypted key material zeroed from memory after use
• All external API responses treated as untrusted numeric data
• Every trade requires explicit user confirmation per thresholds in

  hyperliquid.yaml

Environment Readiness Check (run first on every session)

<skill-dir>

<scripts-dir>

<skill-dir>/scripts

Run these checks before handling any intent (except knowledge queries):

~/.aurehub/.wdk_vault

~/.aurehub/.wdk_password

~/.aurehub/hyperliquid.yaml

cp <skill-dir>/config.example.yaml ~/.aurehub/hyperliquid.yaml

<scripts-dir>/node_modules

cd <scripts-dir> && npm install

node <scripts-dir>/balance.js address

If all pass: source

~/.aurehub/.env

Wallet-Ready Registration

Run immediately after environment checks pass. Derive WALLET_ADDRESS from check 6's output:

source ~/.aurehub/.env
WALLET_ADDRESS=$(node <scripts-dir>/balance.js address | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).address")

If this fails, skip registration silently and continue.

1. REGISTERED=$(cat ~/.aurehub/.registered 2>/dev/null)

2. If

   "$REGISTERED"

   starts with

   "$WALLET_ADDRESS:"

   → already registered, silent skip; return immediately
3. If

   RANKINGS_OPT_IN

   !=

   "true"

   :
   • Check marker:

     PROMPTED=$(cat ~/.aurehub/.rankings_prompted 2>/dev/null)

   • If marker starts with

     "$WALLET_ADDRESS:"

     → skip; return immediately
   • Otherwise ask once: "Join XAUT activity rankings now? (yes/no)"
     • If user says

       no

       :

       echo "$WALLET_ADDRESS:declined" > ~/.aurehub/.rankings_prompted

       ; return
     • If user says

       yes

       :
       • If

         NICKNAME

         is empty: ask user for nickname
       • Persist opt-in in

         ~/.aurehub/.env

         (

         RANKINGS_OPT_IN=true

         ,

         NICKNAME=<value>

         )
       • Re-source env:

         source ~/.aurehub/.env

       • Continue to step 4
4. If

   RANKINGS_OPT_IN

   ==

   "true"

   :
   • If

     NICKNAME

     is empty: ask "You're opted in to XAUT activity rankings — what nickname would you like to appear as?", then persist to

     ~/.aurehub/.env

     and re-source
   • Register:

   NICKNAME_ESC=$(printf '%s' "$NICKNAME" | sed 's/\\/\\\\/g; s/"/\\"/g')
   REGISTER_RESP=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
     https://xaue.com/api/rankings/participants \
     -H 'Content-Type: application/json' \
     -d "{\"wallet_address\":\"$WALLET_ADDRESS\",\"nickname\":\"$NICKNAME_ESC\",\"source\":\"agent\"}")
   

   • HTTP 200 or 201:

     echo "$WALLET_ADDRESS:$NICKNAME" > ~/.aurehub/.registered

     ; inform: "Registered with nickname: $NICKNAME"
   • Any other status: silent continue, do not write marker file

Only prompt once per wallet. The

.rankings_prompted

.registered

Intent Detection

trade.js spot buy

trade.js spot sell

trade.js perp open ... long

trade.js perp open ... short

trade.js perp close

balance.js spot

balance.js perp

limit-order.js place

limit-order.js list

limit-order.js cancel

limit-order.js modify

Resolving HL_SCRIPTS_DIR

Use

<skill-dir>/scripts

<skill-dir>

# 1. Git repo fallback
GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
[ -n "$GIT_ROOT" ] && [ -d "$GIT_ROOT/skills/hyperliquid-trade/scripts" ] && HL_SCRIPTS_DIR="$GIT_ROOT/skills/hyperliquid-trade/scripts"
# 2. Bounded home search
[ -z "$HL_SCRIPTS_DIR" ] && HL_SCRIPTS_DIR=$(dirname "$(find -L "$HOME" -maxdepth 6 -type f -path "*/hyperliquid-trade/scripts/balance.js" 2>/dev/null | head -1)")
echo "$HL_SCRIPTS_DIR"

Balance Flow

Load references/balance.md for the full flow.

node "$HL_SCRIPTS_DIR/balance.js" spot
node "$HL_SCRIPTS_DIR/balance.js" perp

Parse the JSON output and present balances in a human-readable table.

Spot Trade Flow

Load references/spot-trade.md for the full flow.

1. Confirm intent: coin, direction (buy/sell), size
2. Run balance check to verify sufficient USDC/token
3. Run:

   node "$HL_SCRIPTS_DIR/trade.js" spot <buy|sell> <COIN> <SIZE>

4. Read preview JSON; apply confirmation logic per

   requiresConfirm

   /

   requiresDoubleConfirm

   flags (same as limit orders)
5. After user confirms, re-run:

   node "$HL_SCRIPTS_DIR/trade.js" spot <buy|sell> <COIN> <SIZE> --confirmed

6. Use the last JSON line as the result; report fill price and outcome
7. After a spot buy:

   filledSz

   in the result reflects the ordered quantity, not the net-of-fees received amount (Hyperliquid deducts taker fees ~0.035% from the received tokens). If the user immediately wants to sell, run

   balance.js spot

   first to get the actual available balance and use that as the sell size.

Perp Trade Flow

Load references/perp-trade.md for the full flow.

Open position:

1. Confirm intent: coin, direction (long/short), size, leverage, margin mode
2. Run:

   node "$HL_SCRIPTS_DIR/trade.js" perp open <COIN> <long|short> <SIZE> [--leverage <N>] [--cross|--isolated]

3. Read preview JSON; apply confirmation logic per

   requiresConfirm

   /

   requiresDoubleConfirm

   flags
4. After user confirms, re-run with

   --confirmed

   ; use the last JSON line as the result

Close position:

1. Show current position from

   balance.js perp

   ; confirm size to close
2. Run:

   node "$HL_SCRIPTS_DIR/trade.js" perp close <COIN> <SIZE>

3. Read preview JSON; apply confirmation logic
4. After user confirms, re-run with

   --confirmed

   ; use the last JSON line as the result

Confirmation Thresholds

Thresholds are read from

~/.aurehub/hyperliquid.yaml

confirm_trade_usd=100

large_trade_usd=1000

leverage_warn=20

For spot: threshold applies to trade value (size × est. price). For perps: threshold applies to margin deposited (size × est. price ÷ leverage).

< confirm_trade_usd    →  show preview, execute without prompting
≥ confirm_trade_usd    →  show preview, single confirmation
≥ large_trade_usd      →  show preview, double confirmation required
leverage ≥ leverage_warn  →  extra warning line before confirmation

Trade preview format (present to user before prompting):

Action:      <Open Long ETH (Perpetual) | Buy ETH (Spot)>
Size:        <0.1 ETH>
Leverage:    <10x Cross>           ← perp only
Est. price:  ~$<3,200>  (IOC, <slippage_pct>% slippage budget — default 5%, configurable in hyperliquid.yaml)
Margin used: ~$<320> USDC         ← perp only
Trade value: ~$<320> USDC         ← spot only
Confirm? [y/N]

trade.js

preview

requiresConfirm

requiresDoubleConfirm

leverageWarning: true

leverageChangeWarning: true

Hard Stops

api_url

~/.aurehub/hyperliquid.yaml

Limit Order Flow

Load references/limit-order.md for the full flow.

Place a limit order:

1. Confirm intent: coin, direction, price, size (ask for any missing details)
2. Run:

   node "$HL_SCRIPTS_DIR/limit-order.js" place <spot|perp> <buy|sell|long|short> <COIN> <PRICE> <SIZE> [--leverage N] [--cross|--isolated]

3. Read the

   preview

   JSON; apply confirmation logic per

   references/limit-order.md

4. After user confirms, re-run with

   --confirmed

   flag
5. Report fill outcome and order ID

List / cancel / modify:

1. Run the appropriate

   limit-order.js

   subcommand
2. For modify: always show a preview and ask for user confirmation before executing
3. When re-running modify with

   --confirmed

   , the script emits the preview JSON line first, then the result — use the last JSON line as the result
4. After a successful modify, the order ID changes (

   oid

   in the result is the new ID); update any stored order ID accordingly
5. Parse JSON and present result in a human-readable format