hyperliquid-orders

Documentación de origen, no instrucciones para este sitio. Revisa los permisos antes de ejecutar comandos.

import os, secrets
from decimal import Decimal, ROUND_DOWN, ROUND_HALF_UP
import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants
from hyperliquid.utils.types import Cloid

def load_key():
    k = os.environ.get("HYPERLIQUID_PRIVATE_KEY")
    if not k:
        p = os.path.expanduser("~/.hyperliquid/api-wallet.key")
        if os.path.exists(p):
            k = open(p).read().strip()
    if not k:
        raise SystemExit("no API wallet key available - see hyperliquid-setup section 4")
    return k

NETWORK = os.environ.get("HYPERLIQUID_NETWORK", "testnet")
BASE = constants.MAINNET_API_URL if NETWORK == "mainnet" else constants.TESTNET_API_URL
ACCOUNT = os.environ["HYPERLIQUID_ACCOUNT_ADDRESS"]           # main account the API wallet acts for

info = Info(BASE, skip_ws=True)
exchange = Exchange(eth_account.Account.from_key(load_key()), BASE, account_address=ACCOUNT)

SZ_DECIMALS = {a["name"]: a["szDecimals"] for a in info.meta()["universe"]}

def round_px(coin, px, spot=False):
    """5 significant figures, then at most (6|8) - szDecimals decimals. Integers are always valid,
    so above 100,000 keep whole-dollar precision instead of rounding to tens."""
    px = float(px)
    if px >= 100_000:
        return float(round(px))
    max_dec = max((8 if spot else 6) - SZ_DECIMALS[coin], 0)
    px = float(f"{px:.5g}")
    return float(Decimal(str(px)).quantize(Decimal(1).scaleb(-max_dec), rounding=ROUND_HALF_UP))

def round_sz(coin, sz):
    """Round DOWN to szDecimals (Decimal, so 0.29 stays 0.29 and never becomes 0.28)."""
    return float(Decimal(str(sz)).quantize(Decimal(1).scaleb(-SZ_DECIMALS[coin]), rounding=ROUND_DOWN))

def new_cloid():
    return Cloid.from_str("0x" + secrets.token_hex(16))

coin, is_buy, sz, px = "ETH", True, round_sz("ETH", 0.51), round_px("ETH", 3000)
assert sz * px >= 10, "below 10 USD minimum order value"
cloid = new_cloid()
print("cloid", cloid.to_raw())                     # write this to the proposal file BEFORE sending
res = exchange.order(coin, is_buy, sz, px, {"limit": {"tif": "Gtc"}}, reduce_only=False, cloid=cloid)
print(res)

coin, is_buy, sz, slippage = "ETH", True, round_sz("ETH", 0.51), 0.002      # 20 bps
mid = float(info.all_mids()[coin])
px = round_px(coin, mid * (1 + slippage) if is_buy else mid * (1 - slippage))
cloid = new_cloid(); print("cloid", cloid.to_raw(), "bound px", px)
res = exchange.order(coin, is_buy, sz, px, {"limit": {"tif": "Ioc"}}, reduce_only=False, cloid=cloid)
print(res)
# The SDK also offers exchange.market_open(coin, is_buy, sz, px=None, slippage=0.01, cloid=cloid): same semantics,
# it rounds the PRICE for you but not the size (pass round_sz), and its default slippage is 5% if you omit it.
# State the slippage bound in the report either way.

coin, sz = "ETH", round_sz("ETH", 0.51)
bound_tp, bound_sl = 0.01, 0.05                                   # worst-acceptable price after trigger (desk defaults)
entry, tp, sl = round_px(coin, 3000), round_px(coin, 3090), round_px(coin, 2900)
tp_px, sl_px = round_px(coin, tp * (1 - bound_tp)), round_px(coin, sl * (1 - bound_sl))   # sells: p below trigger
c_entry, c_tp, c_sl = new_cloid(), new_cloid(), new_cloid()
orders = [
  {"coin": coin, "is_buy": True,  "sz": sz, "limit_px": entry, "order_type": {"limit": {"tif": "Gtc"}}, "reduce_only": False, "cloid": c_entry},
  {"coin": coin, "is_buy": False, "sz": sz, "limit_px": tp_px, "order_type": {"trigger": {"triggerPx": tp, "isMarket": True, "tpsl": "tp"}}, "reduce_only": True, "cloid": c_tp},
  {"coin": coin, "is_buy": False, "sz": sz, "limit_px": sl_px, "order_type": {"trigger": {"triggerPx": sl, "isMarket": True, "tpsl": "sl"}}, "reduce_only": True, "cloid": c_sl},
]
res = exchange.bulk_orders(orders, grouping="normalTpsl")   # entry + children as one-cancels-other
print(res)

coin, bound = "ETH", 0.05                        # 5% worst-acceptable bound for a stop-loss
pos = next(p["position"] for p in info.user_state(ACCOUNT)["assetPositions"] if p["position"]["coin"] == coin)
szi = float(pos["szi"])                          # positive long, negative short
sz, is_buy_close = round_sz(coin, abs(szi)), szi < 0
trigger = round_px(coin, 2900)
worst = round_px(coin, trigger * (1 + bound) if is_buy_close else trigger * (1 - bound))
res = exchange.order(coin, is_buy_close, sz, worst,
                     {"trigger": {"triggerPx": trigger, "isMarket": True, "tpsl": "sl"}},
                     reduce_only=True, cloid=new_cloid())
print(res)

exchange.cancel("ETH", oid)                                    # by exchange order id
exchange.cancel_by_cloid("ETH", Cloid.from_str("0x..."))       # by client order id
exchange.bulk_cancel([{"coin": "ETH", "oid": 1}, {"coin": "BTC", "oid": 2}])
# statuses: ["success"] or [{"error": "Order was never placed, already canceled, or filled."}]

# Modify = cancel the resting order and place the new one in one action (the SDK sends batchModify).
# oid may be an int or a Cloid. The replacement gets a NEW oid; pass a fresh cloid and record it.
res = exchange.modify_order(oid, "ETH", True, round_sz("ETH", 0.51), round_px("ETH", 2995),
                            {"limit": {"tif": "Gtc"}}, reduce_only=False, cloid=new_cloid())
print(res)   # statuses like an order response: resting / filled / error

if res.get("status") == "ok":
    for st in res["response"]["data"]["statuses"]:
        if "resting" in st:      print("resting oid", st["resting"]["oid"])
        elif "filled" in st:     print("filled", st["filled"]["totalSz"], "@", st["filled"]["avgPx"], "oid", st["filled"]["oid"])
        elif st in ("waitingForTrigger", "waitingForFill"): print(st)
        elif "error" in st:      print("REJECTED:", st["error"])
else:
    print("ACTION REJECTED:", res.get("response"))

name: hyperliquid-orders
description: Place, cancel and modify Hyperliquid orders correctly from the desk computer - limit and IOC (market-style) orders, take-profit and stop-loss trigger orders with grouping, client order ids, reduce-only, batch actions, price and size rounding, and how to read every response status. Write path - Execution Trader only, on an approved ticket. Use for any order action and for reconciling by cloid.
license: MIT
metadata:
  version: "1.1.0"
  author: Galleon Labs
  category: hyperliquid
  network-default: testnet

---
name: hyperliquid-orders
description: Place, cancel and modify Hyperliquid orders correctly from the desk computer - limit and IOC (market-style) orders, take-profit and stop-loss trigger orders with grouping, client order ids, reduce-only, batch actions, price and size rounding, and how to read every response status. Write path - Execution Trader only, on an approved ticket. Use for any order action and for reconciling by cloid.
license: MIT
metadata:
  version: "1.1.0"
  author: Galleon Labs
  category: hyperliquid
  network-default: testnet
---

# Hyperliquid orders

Everything here ends in a signed request to `/exchange`. On this desk only the Execution Trader runs it, only on a ticket with a Risk PASS and the user's approval by id, and only once per approval (`desk-execution-protocol`). Reads used for reconciliation are in `hyperliquid-account`.

## Concepts you must get right

- **Asset index, not symbol.** Perps use the index of the coin in `meta.universe` (BTC is 0 on mainnet, but never hardcode: read `meta`). Spot uses `10000 + index` in `spotMeta.universe`. The Python SDK's `Exchange` accepts the coin name and resolves the index; the TS SDK wants the number.
- **Price rounding.** At most 5 significant figures, and at most `6 - szDecimals` decimal places for perps (`8 - szDecimals` for spot). Integer prices are always valid. Wrong precision is rejected by the exchange.
- **Size rounding.** Round **down** to the market's `szDecimals`. Never round up.
- **Minimum order value** is 10 USD notional.
- **Time in force:** `Gtc` rests until filled or cancelled; `Ioc` fills what it can immediately and cancels the rest; `Alo` (add liquidity only) rests or is rejected if it would take.
- **There is no market order.** A market-style order is an `Ioc` limit at a price bounded by your slippage tolerance (buy: above mid; sell: below mid).
- **reduceOnly** orders can only reduce an existing position; use it for exits, stops and take-profits.
- **cloid** (client order id) is `0x` + 32 hex characters (16 bytes). Unique per order. It lets you query and cancel an order even if the response was lost.
- **Trigger orders** (`tp`/`sl`): `triggerPx` is the **mark price** that arms the order; `isMarket: true` executes market-style once triggered, `false` places a limit at `p`. `p` is always required and acts as the worst-acceptable price after the trigger, so for market triggers set it beyond the trigger: a sell trigger's `p` below `triggerPx`, a buy trigger's `p` above it. A stop whose `p` equals its trigger can rest unfilled through a gap, so the desk defaults to a **5% bound for stop-losses** (filling matters more than slippage) and **1% for take-profits**; the app uses 10% for both. The ticket may override.
- **Grouping**: `na` (independent orders); `normalTpsl` (entry plus TP/SL as one-cancels-other tied to that entry: children are sized to the entry, placed only when it fills, cancelled if it is cancelled, and when one child fills the sibling is cancelled); `positionTpsl` (TP/SL tied to the position rather than to an order, shown as the position's own TP/SL, `isPositionTpsl: true`). Every TP/SL with an explicit size is **fixed-size** once placed; it does not resize when the position changes. The app's "entire position" TP/SL is a reduce-only trigger sent with size `0` under `positionTpsl` grouping (such orders show up live in `frontendOpenOrders` as `sz: "0.0"`, `isPositionTpsl: true`); rehearse it on testnet before the desk relies on it.
- **Responses:** each order in an action gets a status: `{"resting": {"oid": ...}}`, `{"filled": {"totalSz", "avgPx", "oid"}}`, `"waitingForTrigger"`, `"waitingForFill"`, or `{"error": "..."}`. A top-level `{"status": "err", "response": "..."}` means the whole action was rejected.

## Python (official SDK, `hyperliquid-python-sdk`)

Common header for every snippet below (network, account, key loader, rounding helpers):

```python
import os, secrets
from decimal import Decimal, ROUND_DOWN, ROUND_HALF_UP
import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants
from hyperliquid.utils.types import Cloid

def load_key():
    k = os.environ.get("HYPERLIQUID_PRIVATE_KEY")
    if not k:
        p = os.path.expanduser("~/.hyperliquid/api-wallet.key")
        if os.path.exists(p):
            k = open(p).read().strip()
    if not k:
        raise SystemExit("no API wallet key available - see hyperliquid-setup section 4")
    return k

NETWORK = os.environ.get("HYPERLIQUID_NETWORK", "testnet")
BASE = constants.MAINNET_API_URL if NETWORK == "mainnet" else constants.TESTNET_API_URL
ACCOUNT = os.environ["HYPERLIQUID_ACCOUNT_ADDRESS"]           # main account the API wallet acts for

info = Info(BASE, skip_ws=True)
exchange = Exchange(eth_account.Account.from_key(load_key()), BASE, account_address=ACCOUNT)

SZ_DECIMALS = {a["name"]: a["szDecimals"] for a in info.meta()["universe"]}

def round_px(coin, px, spot=False):
    """5 significant figures, then at most (6|8) - szDecimals decimals. Integers are always valid,
    so above 100,000 keep whole-dollar precision instead of rounding to tens."""
    px = float(px)
    if px >= 100_000:
        return float(round(px))
    max_dec = max((8 if spot else 6) - SZ_DECIMALS[coin], 0)
    px = float(f"{px:.5g}")
    return float(Decimal(str(px)).quantize(Decimal(1).scaleb(-max_dec), rounding=ROUND_HALF_UP))

def round_sz(coin, sz):
    """Round DOWN to szDecimals (Decimal, so 0.29 stays 0.29 and never becomes 0.28)."""
    return float(Decimal(str(sz)).quantize(Decimal(1).scaleb(-SZ_DECIMALS[coin]), rounding=ROUND_DOWN))

def new_cloid():
    return Cloid.from_str("0x" + secrets.token_hex(16))
```

### Resting limit order (Gtc)

```python
coin, is_buy, sz, px = "ETH", True, round_sz("ETH", 0.51), round_px("ETH", 3000)
assert sz * px >= 10, "below 10 USD minimum order value"
cloid = new_cloid()
print("cloid", cloid.to_raw())                     # write this to the proposal file BEFORE sending
res = exchange.order(coin, is_buy, sz, px, {"limit": {"tif": "Gtc"}}, reduce_only=False, cloid=cloid)
print(res)
```

### Market-style order (IOC with a slippage bound)

```python
coin, is_buy, sz, slippage = "ETH", True, round_sz("ETH", 0.51), 0.002      # 20 bps
mid = float(info.all_mids()[coin])
px = round_px(coin, mid * (1 + slippage) if is_buy else mid * (1 - slippage))
cloid = new_cloid(); print("cloid", cloid.to_raw(), "bound px", px)
res = exchange.order(coin, is_buy, sz, px, {"limit": {"tif": "Ioc"}}, reduce_only=False, cloid=cloid)
print(res)
# The SDK also offers exchange.market_open(coin, is_buy, sz, px=None, slippage=0.01, cloid=cloid): same semantics,
# it rounds the PRICE for you but not the size (pass round_sz), and its default slippage is 5% if you omit it.
# State the slippage bound in the report either way.
```

### Entry with stop-loss and take-profit in one action

```python
coin, sz = "ETH", round_sz("ETH", 0.51)
bound_tp, bound_sl = 0.01, 0.05                                   # worst-acceptable price after trigger (desk defaults)
entry, tp, sl = round_px(coin, 3000), round_px(coin, 3090), round_px(coin, 2900)
tp_px, sl_px = round_px(coin, tp * (1 - bound_tp)), round_px(coin, sl * (1 - bound_sl))   # sells: p below trigger
c_entry, c_tp, c_sl = new_cloid(), new_cloid(), new_cloid()
orders = [
  {"coin": coin, "is_buy": True,  "sz": sz, "limit_px": entry, "order_type": {"limit": {"tif": "Gtc"}}, "reduce_only": False, "cloid": c_entry},
  {"coin": coin, "is_buy": False, "sz": sz, "limit_px": tp_px, "order_type": {"trigger": {"triggerPx": tp, "isMarket": True, "tpsl": "tp"}}, "reduce_only": True, "cloid": c_tp},
  {"coin": coin, "is_buy": False, "sz": sz, "limit_px": sl_px, "order_type": {"trigger": {"triggerPx": sl, "isMarket": True, "tpsl": "sl"}}, "reduce_only": True, "cloid": c_sl},
]
res = exchange.bulk_orders(orders, grouping="normalTpsl")   # entry + children as one-cancels-other
print(res)
```

Sell-side entries mirror this: `is_buy=False`, TP trigger below entry, SL trigger above, children `is_buy=True` with `p` **above** their triggers.

The children come back as `waitingForFill` while the entry rests; they are placed once the entry fills (fully, or partially followed by a margin cancel), cancelled if the entry is cancelled, and when one child fills the sibling is cancelled (`siblingFilledCanceled`). Cancelling a partially filled entry cancels the children too; protect the filled part with a separate stop.

### Stop-loss on an existing position

```python
coin, bound = "ETH", 0.05                        # 5% worst-acceptable bound for a stop-loss
pos = next(p["position"] for p in info.user_state(ACCOUNT)["assetPositions"] if p["position"]["coin"] == coin)
szi = float(pos["szi"])                          # positive long, negative short
sz, is_buy_close = round_sz(coin, abs(szi)), szi < 0
trigger = round_px(coin, 2900)
worst = round_px(coin, trigger * (1 + bound) if is_buy_close else trigger * (1 - bound))
res = exchange.order(coin, is_buy_close, sz, worst,
                     {"trigger": {"triggerPx": trigger, "isMarket": True, "tpsl": "sl"}},
                     reduce_only=True, cloid=new_cloid())
print(res)
```

This is a standalone reduce-only trigger (`grouping="na"`, as in the official SDK example) with a fixed size: after a partial fill, an add or a reduce, place a new stop for the actual size and then cancel the old one. The alternative is the app's position-tied form: the same trigger with `sz=0` submitted via `bulk_orders([...], grouping="positionTpsl")`, which closes whatever the position is when it fires (`frontendOpenOrders` shows it as `sz: "0.0"`, `isPositionTpsl: true`). Rehearse the size-0 form on testnet before using it on mainnet.

### Cancel

```python
exchange.cancel("ETH", oid)                                    # by exchange order id
exchange.cancel_by_cloid("ETH", Cloid.from_str("0x..."))       # by client order id
exchange.bulk_cancel([{"coin": "ETH", "oid": 1}, {"coin": "BTC", "oid": 2}])
# statuses: ["success"] or [{"error": "Order was never placed, already canceled, or filled."}]
```

Cancel-all-for-account does not exist as one action; list `open_orders(ACCOUNT)` and cancel each, or use the dead-man's switch (`hyperliquid-advanced`).

### Modify

```python
# Modify = cancel the resting order and place the new one in one action (the SDK sends batchModify).
# oid may be an int or a Cloid. The replacement gets a NEW oid; pass a fresh cloid and record it.
res = exchange.modify_order(oid, "ETH", True, round_sz("ETH", 0.51), round_px("ETH", 2995),
                            {"limit": {"tif": "Gtc"}}, reduce_only=False, cloid=new_cloid())
print(res)   # statuses like an order response: resting / filled / error
```

Limits that matter: without the raw `always_place` flag (which the SDK's `modify_order` never sets and the desk does not use), the replacement **must be a non-trigger order that will rest** - `Alo`, or a `Gtc` that would not execute immediately. So `modify` is for moving or resizing a resting limit order. **Stops and take-profits cannot be modified**: place the new trigger order first, confirm it is resting, then cancel the old one, so the position is never unprotected. If the original order was already filled or cancelled, the modify fails and nothing new is placed.

### Read the response

```python
if res.get("status") == "ok":
    for st in res["response"]["data"]["statuses"]:
        if "resting" in st:      print("resting oid", st["resting"]["oid"])
        elif "filled" in st:     print("filled", st["filled"]["totalSz"], "@", st["filled"]["avgPx"], "oid", st["filled"]["oid"])
        elif st in ("waitingForTrigger", "waitingForFill"): print(st)
        elif "error" in st:      print("REJECTED:", st["error"])
else:
    print("ACTION REJECTED:", res.get("response"))
```

Then reconcile: `info.query_order_by_cloid(ACCOUNT, cloid)`, `info.open_orders(ACCOUNT)`, `info.user_fills(ACCOUNT)