Setup
1. Install CLI
which hl1m
If hl1m is missing, install the 1m-trade package (requires Python 3.11+ and pipx):
- If
pipx exists: pipx install 1m-trade
- If
pipx is missing:
- Linux: install
pipx via apt / yum / dnf
- macOS:
brew install pipx
- Windows:
python -m pip install --user pipx then python -m pipx ensurepath
pipx install 1m-trade
2. Verify
hl1m --help
3. Upgrade
pipx upgrade 1m-trade
Basic syntax
hl1m [--testnet] <command> [command_args]
Core flags
--testnet: use Hyperliquid testnet (default: mainnet)
Wallet initialization
Official wallet UI (create & manage):
- For creating a wallet and managing it (addresses, keys, proxy/API settings as offered by the product), direct users to 1M-Trade in the browser. Do not recreate that flow inside chat.
- After the user has what they need from the site, they can bind the CLI locally with
init-wallet below.
When to trigger: user wants to use their own wallet with this skill (e.g. “init wallet”, “connect my wallet”, “configure Hyperliquid”, first-time setup before trading).
Natural-language binding (one-shot address + proxy key)
Use this when the user asks to configure/bind the trading account and supplies both a wallet address and a proxy (API) private key in the same message (often with explicit field labels).
Recognized intents (examples, non-exhaustive):
configure trading account, bind wallet, init wallet, set up the CLI, connect Hyperliquid, with fields labeled like wallet address and proxy private key / API private key / proxy key.
- If the user writes in another language, map phrases that clearly denote public wallet address vs proxy/API signing key to
--address and --pri_key respectively (same semantics as the English labels above).
Label → flag mapping:
| User wording (meaning) |
hl1m flag |
wallet address, address, or any label clearly referring to the public trading / master address shown in the UI |
--address |
proxy private key, API private key, proxy key, or any label clearly referring to the bot/API signing key — not the main EOA key |
--pri_key |
Parsing (apply before running init-wallet):
- Extract address: first
0x + 40 hexadecimal characters (case-insensitive), typically the value next to a label for the public wallet / address when labels exist.
- Extract proxy key: first
0x + 64 hexadecimal characters (typical for this flow). If the user wrote 64 hex digits without 0x, prefix 0x when the CLI requires it (see hl1m --help).
- Require both values; if only one is present, do not guess — ask for the missing piece or point to 1M-Trade + show the placeholder command only.
- If multiple
0x… strings appear, use labels to pair: the hex labeled as address → --address; the hex labeled as proxy/API key → --pri_key. Do not swap.
Exact command (values come from the user message; run in a trusted local shell):
hl1m init-wallet --address <parsed_address> --pri_key <parsed_proxy_private_key>
Assistant output: confirm bind success or CLI error; run hl1m query-user-state after success. Do not repeat the full private key in chat (mask or omit).
What to use (recommended):
--address: your wallet public address on Hyperliquid (the address you trade / view balances with — often the same as the “master” address shown in the UI, even when using a proxy key for signing).
--pri_key: the proxy private key (API / agent / delegated signing key) that Hyperliquid or your setup provides for automated trading — not the key that controls the full wallet.
Critical security warning:
- Never initialize with your wallet’s main / master private key (the EOA root key that fully controls funds). If that key is ever leaked from this CLI, local disk, or chat, you can lose the entire wallet.
- Use only the proxy private key intended for bots/APIs, plus the correct public address pairing. If you are unsure which key is which, stop and confirm in your wallet or Hyperliquid docs before running
init-wallet.
Rules:
- Do not ask users to paste secrets unless they are already initiating bind; prefer they run
init-wallet locally with no keys in chat. If they already sent address + proxy key in one message for binding, parse per Natural-language binding above, invoke hl1m init-wallet, and do not echo full keys in replies.
- You only execute
hl1m commands; do not edit skill files or read .env contents into the model context.
Command (placeholders — user substitutes on their machine; never paste real keys in chat):
hl1m init-wallet --address 0xYourWalletAddress --pri_key 0xYourProxyPrivateKey
--address: wallet public address (see above).
--pri_key: proxy private key for signing — not the main wallet private key.
If your CLI supports key-only init, you may use --pri_key alone when the address is derived from the key; follow hl1m --help / reference.md for your version.
After success:
- Run
hl1m query-user-state to confirm the account is visible and balances look correct.
Constraints
- If the user cannot open a position (e.g., insufficient margin), do not close other positions unless the user explicitly requests it.
Command list
Note: for any asset name (e.g. --coin), you can run query-meta to confirm the exact symbol. For example, user input "gold" often maps to xyz:GOLD. Always pass the canonical symbol.
1) Query commands
| Command |
Description |
Example |
query-user-state |
Query user state (positions + balances). Optional address override; structure follows the API/SDK response. |
hl1m query-user-state --address 0x123... |
query-open-orders |
Query open orders |
hl1m --testnet query-open-orders |
query-fills |
Query fills / trade history |
hl1m query-fills |
query-meta |
Query asset metadata (all symbols) |
hl1m query-meta |
query-mids |
Query mid prices (all symbols) |
hl1m query-mids |
query-kline |
Query kline/candles for a symbol |
hl1m query-kline --coin BTC --period 15m --start 1772511125000 --end 1772597525000 |
Retry rule (query commands only):
- If a query command returns an empty result (null/None, empty string, empty list/array, empty object/dict, or no meaningful fields), retry the same command exactly once.
- Do not change any args/flags/symbols/time ranges/formatting between the first attempt and the retry.
- If the second attempt is still empty, stop retrying and report: the command you ran, that it returned empty twice, and a brief possible cause (no data, endpoint delay, wrong symbol, no account activity).
Query command arguments
query-user-state
--address: optional. If omitted, the address is derived from the configured private key.
query-kline
--coin: required. Symbol such as BTC, ETH, or xyz:TSLA. Use query-meta to confirm the canonical symbol first.
--period: required. One of: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M.
--start: optional (ms). Default is the start of the last 24 hours.
--end: optional (ms). Default is the current timestamp in ms.
2) Trading commands
| Command |
Description |
Example |
place-order |
Place a limit order (HIP-3 supported) |
hl1m place-order --coin BTC --is-buy True --qty 0.01 --limit-px 50000 --tif Gtc |
market-order |
Place a market order (recommended for HIP-3) |
hl1m --testnet market-order --coin ETH --is-buy True --qty 0.1 --slippage 0.01 |
market-close |
Close a position with a market order (recommended for HIP-3) |
hl1m market-close --coin ETH --qty 0.1 --slippage 0.01 |
cancel-order |
Cancel orders |
hl1m cancel-order --oid 123456 --coin HYPE |
update-leverage |
Update leverage |
hl1m update-leverage --coin BTC --leverage 10 --is-cross True |
update-isolated-margin |
Transfer isolated margin (HIP-3) |
hl1m update-isolated-margin --coin xyz:GOLD --amount 10 |
Trading command arguments
General rules
- For
--coin, always resolve the canonical symbol (use query-meta if needed).
- For
--qty, use query-meta results (e.g. szDecimals) to format the quantity precision correctly.
update-isolated-margin
--coin: required. Canonical symbol.
--amount: required. Transfer amount.
place-order
--coin: required.
--is-buy: required (True/False). True = long, False = short.
--qty: required.
--limit-px: required.
--tif: optional (Gtc/Ioc/Alo, default Gtc).
--reduce-only: optional (default False).
market-order
--coin: required.
--is-buy: required (True/False). True = long, False = short.
--qty: required.
--slippage: optional (default 0.02 = 2%).
market-close
--coin: required.
--qty: required.
--slippage: optional (default 0.02 = 2%).
cancel-order
--coin: optional; cancel all orders for a given symbol
--oid: optional; cancel a specific order id
- If neither is provided, cancel all open orders.
update-leverage
--coin: required.
--leverage: required (integer).
--is-cross: optional (True/False, default True).
Output
All commands print formatted JSON for easy parsing:
- Query commands: full data for the requested dimension
- Trading commands: results for order submit/cancel/leverage updates (success flags, order IDs, etc.)
Error handling
- Network issues: handled by the SDK with error messages
- Invalid trading parameters: returns official Hyperliquid error responses
Notes
- Private keys are sensitive. Do not expose or share them.
- Testnet vs mainnet are strictly separated. Confirm
--testnet before acting.
- Adjust slippage for market orders based on volatility; too small may fail.
- Leverage trading is risky. Choose leverage carefully.
- For proxy-style setups, follow
hl1m help for --address / --pri_key behavior.
Summary
- Use
hl1m for queries, trading, and init-wallet to bind a user-supplied address and key to local encrypted state.
- Install via
pipx install 1m-trade (or your package manager); see hl1m --help and reference.md for full flags.
1---2name: 1m-trade-dex3description: |4 Hyperliquid DEX/Perps entrypoint via `hl1m`: market queries, order placement. Wallet creation/management at https://www.1m-trade.com; local `hl1m init-wallet` with address + proxy (API) private key — never the main wallet key. No in-skill private-key messaging.5requires:6 bins: [hl1m]7install:8 - pipx install 1m-trade9metadata:10 source: https://skillmd.com/skills/leoyeai-openclaw-master-skills/1m-trade-dex11 openclaw:12 emoji: "🚀"13 os: [darwin, linux, win32]14 tags: [crypto, news, trading, hyperliquid, wallet, dex, automation]15---1617## Setup1819### 1. Install CLI2021```bash22which hl1m23```2425If `hl1m` is missing, install the `1m-trade` package (requires Python 3.11+ and `pipx`):2627- If `pipx` exists: `pipx install 1m-trade`28- If `pipx` is missing:29 - Linux: install `pipx` via `apt` / `yum` / `dnf`30 - macOS: `brew install pipx`31 - Windows: `python -m pip install --user pipx` then `python -m pipx ensurepath`3233```bash34pipx install 1m-trade35```3637### 2. Verify3839```bash40hl1m --help41```4243### 3. Upgrade4445```bash46pipx upgrade 1m-trade47```4849### Basic syntax5051```bash52hl1m [--testnet] <command> [command_args]53```5455### Core flags5657- `--testnet`: use Hyperliquid testnet (default: mainnet)5859---6061## Wallet initialization6263**Official wallet UI (create & manage)**:6465- For **creating a wallet** and **managing** it (addresses, keys, proxy/API settings as offered by the product), direct users to **[1M-Trade](https://www.1m-trade.com)** in the browser. Do not recreate that flow inside chat.66- After the user has what they need from the site, they can bind the CLI locally with `init-wallet` below.6768**When to trigger**: user wants to use their own wallet with this skill (e.g. “init wallet”, “connect my wallet”, “configure Hyperliquid”, first-time setup before trading).6970### Natural-language binding (one-shot address + proxy key)7172Use this when the user **asks to configure/bind the trading account** and **supplies both** a wallet address and a proxy (API) private key in the **same message** (often with explicit field labels).7374**Recognized intents (examples, non-exhaustive)**:7576- `configure trading account`, `bind wallet`, `init wallet`, `set up the CLI`, `connect Hyperliquid`, with fields labeled like `wallet address` and `proxy private key` / `API private key` / `proxy key`.77- If the user writes in another language, map phrases that clearly denote **public wallet address** vs **proxy/API signing key** to `--address` and `--pri_key` respectively (same semantics as the English labels above).7879**Label → flag mapping**:8081| User wording (meaning) | `hl1m` flag |82|------------------------|-------------|83| `wallet address`, `address`, or any label clearly referring to the public trading / master address shown in the UI | `--address` |84| `proxy private key`, `API private key`, `proxy key`, or any label clearly referring to the bot/API signing key — **not** the main EOA key | `--pri_key` |8586**Parsing (apply before running `init-wallet`)**:87881. Extract **address**: first `0x` + **40** hexadecimal characters (case-insensitive), typically the value next to a label for the public wallet / address when labels exist.892. Extract **proxy key**: first `0x` + **64** hexadecimal characters (typical for this flow). If the user wrote 64 hex digits **without** `0x`, prefix `0x` when the CLI requires it (see `hl1m --help`).903. Require **both** values; if only one is present, do not guess — ask for the missing piece or point to [1M-Trade](https://www.1m-trade.com) + show the placeholder command only.914. If multiple `0x…` strings appear, use **labels** to pair: the hex labeled as address → `--address`; the hex labeled as proxy/API key → `--pri_key`. Do not swap.9293**Exact command** (values come from the user message; run in a trusted local shell):9495```bash96hl1m init-wallet --address <parsed_address> --pri_key <parsed_proxy_private_key>97```9899**Assistant output**: confirm bind success or CLI error; run `hl1m query-user-state` after success. **Do not** repeat the full private key in chat (mask or omit).100101**What to use (recommended)**:102103- **`--address`**: your **wallet public address** on Hyperliquid (the address you trade / view balances with — often the same as the “master” address shown in the UI, even when using a proxy key for signing).104- **`--pri_key`**: the **proxy private key** (API / agent / delegated signing key) that Hyperliquid or your setup provides for automated trading — **not** the key that controls the full wallet.105106**Critical security warning**:107108- **Never** initialize with your wallet’s **main / master private key** (the EOA root key that fully controls funds). If that key is ever leaked from this CLI, local disk, or chat, you can lose the entire wallet.109- Use only the **proxy private key** intended for bots/APIs, plus the correct **public address** pairing. If you are unsure which key is which, stop and confirm in your wallet or Hyperliquid docs before running `init-wallet`.110111**Rules**:112113- Do not **ask** users to paste secrets unless they are already initiating bind; prefer they run `init-wallet` locally with no keys in chat. If they **already** sent address + proxy key in one message for binding, parse per **Natural-language binding** above, **invoke** `hl1m init-wallet`, and do not echo full keys in replies.114- You only **execute** `hl1m` commands; do not edit skill files or read `.env` contents into the model context.115116**Command** (placeholders — user substitutes on their machine; never paste real keys in chat):117118```bash119hl1m init-wallet --address 0xYourWalletAddress --pri_key 0xYourProxyPrivateKey120```121122- `--address`: wallet **public address** (see above).123- `--pri_key`: **proxy private key** for signing — **not** the main wallet private key.124125If your CLI supports key-only init, you may use `--pri_key` alone when the address is derived from the key; follow `hl1m --help` / `reference.md` for your version.126127**After success**:128129- Run `hl1m query-user-state` to confirm the account is visible and balances look correct.130131---132133### Constraints134135- If the user cannot open a position (e.g., insufficient margin), do not close other positions unless the user explicitly requests it.136137### Command list138139Note: for any asset name (e.g. `--coin`), you can run `query-meta` to confirm the exact symbol. For example, user input "gold" often maps to `xyz:GOLD`. Always pass the canonical symbol.140141#### 1) Query commands142143| Command | Description | Example |144|------|------|------|145| `query-user-state` | Query user state (positions + balances). Optional address override; structure follows the API/SDK response. | `hl1m query-user-state --address 0x123...` |146| `query-open-orders` | Query open orders | `hl1m --testnet query-open-orders` |147| `query-fills` | Query fills / trade history | `hl1m query-fills` |148| `query-meta` | Query asset metadata (all symbols) | `hl1m query-meta` |149| `query-mids` | Query mid prices (all symbols) | `hl1m query-mids` |150| `query-kline` | Query kline/candles for a symbol | `hl1m query-kline --coin BTC --period 15m --start 1772511125000 --end 1772597525000` |151152**Retry rule (query commands only)**:153154- If a query command returns an empty result (null/None, empty string, empty list/array, empty object/dict, or no meaningful fields), retry the **same command** exactly once.155- Do not change any args/flags/symbols/time ranges/formatting between the first attempt and the retry.156- If the second attempt is still empty, stop retrying and report: the command you ran, that it returned empty twice, and a brief possible cause (no data, endpoint delay, wrong symbol, no account activity).157158### Query command arguments159160#### `query-user-state`161162- `--address`: optional. If omitted, the address is derived from the configured private key.163164#### `query-kline`165166- `--coin`: required. Symbol such as `BTC`, `ETH`, or `xyz:TSLA`. Use `query-meta` to confirm the canonical symbol first.167- `--period`: required. One of: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M`.168- `--start`: optional (ms). Default is the start of the last 24 hours.169- `--end`: optional (ms). Default is the current timestamp in ms.170171#### 2) Trading commands172173| Command | Description | Example |174|------|------|------|175| `place-order` | Place a limit order (HIP-3 supported) | `hl1m place-order --coin BTC --is-buy True --qty 0.01 --limit-px 50000 --tif Gtc` |176| `market-order` | Place a market order (recommended for HIP-3) | `hl1m --testnet market-order --coin ETH --is-buy True --qty 0.1 --slippage 0.01` |177| `market-close` | Close a position with a market order (recommended for HIP-3) | `hl1m market-close --coin ETH --qty 0.1 --slippage 0.01` |178| `cancel-order` | Cancel orders | `hl1m cancel-order --oid 123456 --coin HYPE` |179| `update-leverage` | Update leverage | `hl1m update-leverage --coin BTC --leverage 10 --is-cross True` |180| `update-isolated-margin` | Transfer isolated margin (HIP-3) | `hl1m update-isolated-margin --coin xyz:GOLD --amount 10` |181182### Trading command arguments183184#### General rules1851861. For `--coin`, always resolve the canonical symbol (use `query-meta` if needed).1872. For `--qty`, use `query-meta` results (e.g. `szDecimals`) to format the quantity precision correctly.188189#### `update-isolated-margin`190191- `--coin`: required. Canonical symbol.192- `--amount`: required. Transfer amount.193194#### `place-order`195196- `--coin`: required.197- `--is-buy`: required (True/False). True = long, False = short.198- `--qty`: required.199- `--limit-px`: required.200- `--tif`: optional (`Gtc`/`Ioc`/`Alo`, default `Gtc`).201- `--reduce-only`: optional (default False).202203#### `market-order`204205- `--coin`: required.206- `--is-buy`: required (True/False). True = long, False = short.207- `--qty`: required.208- `--slippage`: optional (default 0.02 = 2%).209210#### `market-close`211212- `--coin`: required.213- `--qty`: required.214- `--slippage`: optional (default 0.02 = 2%).215216#### `cancel-order`217218- `--coin`: optional; cancel all orders for a given symbol219- `--oid`: optional; cancel a specific order id220- If neither is provided, cancel all open orders.221222#### `update-leverage`223224- `--coin`: required.225- `--leverage`: required (integer).226- `--is-cross`: optional (True/False, default True).227228## Output229230All commands print formatted JSON for easy parsing:231232- Query commands: full data for the requested dimension233- Trading commands: results for order submit/cancel/leverage updates (success flags, order IDs, etc.)234235## Error handling236237- Network issues: handled by the SDK with error messages238- Invalid trading parameters: returns official Hyperliquid error responses239240## Notes2411. Private keys are sensitive. Do not expose or share them.2422. Testnet vs mainnet are strictly separated. Confirm `--testnet` before acting.2433. Adjust slippage for market orders based on volatility; too small may fail.2444. Leverage trading is risky. Choose leverage carefully.2455. For proxy-style setups, follow `hl1m` help for `--address` / `--pri_key` behavior.246247## Summary248249- Use `hl1m` for queries, trading, and `init-wallet` to bind a user-supplied address and key to local encrypted state.250- Install via `pipx install 1m-trade` (or your package manager); see `hl1m --help` and `reference.md` for full flags.