1m-trade-dex

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:

Parsing (apply before running init-wallet):

1. Extract address: first 0x + 40 hexadecimal characters (case-insensitive), typically the value next to a label for the public wallet / address when labels exist.
2. 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).
3. 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.
4. 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

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

Trading command arguments

General rules

1. For --coin, always resolve the canonical symbol (use query-meta if needed).
2. 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

1. Private keys are sensitive. Do not expose or share them.
2. Testnet vs mainnet are strictly separated. Confirm --testnet before acting.
3. Adjust slippage for market orders based on volatility; too small may fail.
4. Leverage trading is risky. Choose leverage carefully.
5. 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.