# 1m-trade

Hyperliquid trading and query CLI (HIP-3 supported).

## Install

```bash
pip install 1m-trade
```

## Usage

The CLI command is `hl1m`.

It loads environment variables from the OpenClaw state `.env`:

1. `OPENCLAW_STATE_DIR` (if set)
2. otherwise: `~/.openclaw/.1m-trade/.env`

### Quick start

```bash
# trade wallet (shared state .env)
hl1m exchange wallet --pri_key 0x...

# copytrade wallet (optional; if not set, copytrade falls back to trade wallet)
hl1m copy wallet --addr 0x... --pri_key 0x...

# start copytrade
hl1m copy start --leader 0xLeader --target 123

# stop copytrade
hl1m copy stop --target 123
```

## Modules

- **trade**: top-level commands like `query ...`, `exchange ...`
- **copytrade**: `hl1m copy ...` subcommands (start/stop/config/wallet)
- **monitor**: `hl1m monitor run ...` / `hl1m monitor stop ...`
- **analyze**: `hl1m analyze address ...`
- **news**: `hl1m news ...`

## Commands (quick reference)

```bash
# start copy-trading
hl1m copy start --leader 0x... --target 123 [--scale 1.0] [--slippage 0.05] [--coins "BTC,HYPE"]

# stop copy-trading
hl1m copy stop --target 123

# update running parameters
hl1m copy config --target 123 [--scale 1.2] [--max-notional-usd 200] [--max-leverage 10] [--coins "BTC,HYPE"|off]

# monitor addresses
hl1m monitor run --target 123 --user 0x... [--min-notional-usd 0] [--language zh|en]
hl1m monitor stop --target 123 --user 0x...
hl1m monitor stop --target 123 --user all

# analyze one address
hl1m analyze address --addr 0x... [--days 30] [--out report.md] [--out-json report.json]
```

## news commands (quick reference)

`hl1m news ...` uses BlockBeats Pro API and stores the key in the shared state `.env` as `BLOCKBEATS_API_KEY`.

```bash
# set api key
hl1m news set <api_key>

# scenarios
hl1m news snapshot --lang cn
hl1m news fund-flow --network solana
hl1m news macro --timeframe 1M
hl1m news derivatives --data-type 1D --exchanges-size 10

# single endpoints
hl1m news newsflash --type important --size 5 --lang cn
hl1m news article --type important --size 10 --lang cn
hl1m news search --keyword "bitcoin" --size 10 --lang en
hl1m news data --name us10y --type 1M
```

## State `.env` variables

All variables live in the same state file (`~/.openclaw/.1m-trade/.env` by default).

### trade wallet keys (used by trade; also used as fallback by copytrade)

- **`HYPERLIQUID_WALLET_ADDRESS`**: the account address used for queries / user fields
- **`HYPERLIQUID_PRIVATE_KEY_ENC`**: encrypted private key payload (v1)
- **`HYPERLIQUID_PK_ENC_PASSWORD`**: password used to decrypt `HYPERLIQUID_PRIVATE_KEY_ENC`

### copytrade wallet keys (optional; override trade keys for copytrade only)

If these are present, copytrade will use them. If not, copytrade falls back to trade wallet keys above.

- **`1M_TRADE_COPY_WALLET_ADDRESS`**
- **`1M_TRADE_COPY_PRIVATE_KEY_ENC`**
- **`1M_TRADE_COPY_PK_ENC_PASSWORD`**

### news keys

- **`BLOCKBEATS_API_KEY`**: BlockBeats Pro API key (set via `hl1m news set <api_key>`)

### Query examples

```bash
hl1m query user-state
hl1m query open-orders
hl1m query meta
hl1m query kline --coin BTC --period 1m --start 1700000000000 --end 1700003600000
```

### Trading examples

> 需要先初始化 trade 钱包（写入加密私钥到 state `.env`）。

```bash
hl1m exchange place --coin BTC --is-buy true --qty 0.01 --limit-px 60000 --tif Gtc
hl1m exchange market --coin BTC --is-buy true --qty 0.01 --slippage 0.02
hl1m exchange cancel --coin BTC
hl1m exchange leverage --coin BTC --leverage 5 --is-cross true
hl1m exchange close --coin BTC --qty 0.01 --slippage 0.02
```

### Wallet examples

```bash
hl1m exchange wallet --pri_key 0xYourPrivateKey
hl1m exchange wallet --address 0xYourPublicAddress --pri_key 0xYourPrivateKey

# copytrade wallet (optional; separate keys)
hl1m copy wallet --pri_key 0xYourPrivateKey
hl1m copy wallet --addr 0xYourPublicAddress --pri_key 0xYourPrivateKey
```

## License

MIT

