Skip to content本文へ移動
Fabrkntfor HIP-3
Request a reviewレビューを依頼

Trading API & SDK · Placing Orders · 4/8

The Exchange Class

Authentication Setup

The Exchange class handles all authenticated (write) operations. It requires a wallet for signing.

Testnet only. Every sample in this lesson places, cancels or changes real orders. Run them against TESTNET_API_URL with a testnet API wallet.

import os
import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

# Load the API (agent) wallet key from an environment variable
wallet = eth_account.Account.from_key(os.environ["HL_API_WALLET_KEY"])
account_address = os.environ["HL_ACCOUNT_ADDRESS"]  # your main account

exchange = Exchange(
    wallet,
    base_url=constants.TESTNET_API_URL,
    account_address=account_address,
)
info = Info(constants.TESTNET_API_URL, skip_ws=True)

Two kinds of signed actions

The SDK signs with one of two schemes (signing):

Each request carries a nonce; the SDK uses the current time in milliseconds. Nonces are tracked per signer, so give each bot process its own API wallet (nonces).

Placing a Market Order

The API has no separate market order type. market_open reads the mid price, moves it by slippage (default 5%), and sends an aggressive IOC limit order:

# Buy 0.01 BTC at market price (testnet)
result = exchange.market_open(
    name="BTC",
    is_buy=True,
    sz=0.01,       # Size in base asset (BTC)
    slippage=0.01  # Limit price set 1% through the mid
)

print(result)
# {'status': 'ok', 'response': {'type': 'order', 'data': {'statuses': [{'filled': {'totalSz': '0.01', 'avgPx': '...', 'oid': ...}}]}}}

Orders must be worth at least $10 notional.

Placing a Limit Order

# Place a limit buy for 0.01 BTC at $90,000 (testnet)
result = exchange.order(
    name="BTC",
    is_buy=True,
    sz=0.01,
    limit_px=90000.0,
    order_type={"limit": {"tif": "Gtc"}}  # Good-til-cancelled
)

# The response includes the order ID (oid)
if result["status"] == "ok":
    statuses = result["response"]["data"]["statuses"]
    for s in statuses:
        if "resting" in s:
            print(f"Order placed: oid={s['resting']['oid']}")

Time-in-Force Options

The order_type parameter controls how long an order stays active:

TiF Meaning Use Case
Gtc Good-til-cancelled Default for limit orders
Ioc Immediate-or-cancel Fill now or cancel
Alo Add-liquidity-only Post-only: canceled instead of matching

The other order_type form is {"trigger": {"triggerPx": ..., "isMarket": bool, "tpsl": "tp" | "sl"}} for take-profit and stop-loss orders.

# Post-only order (canceled if it would take liquidity)
exchange.order(
    name="ETH",
    is_buy=True,
    sz=0.1,
    limit_px=3000.0,
    order_type={"limit": {"tif": "Alo"}}
)

# IOC order (fill immediately or cancel)
exchange.order(
    name="ETH",
    is_buy=True,
    sz=0.1,
    limit_px=3100.0,
    order_type={"limit": {"tif": "Ioc"}}
)

Cancelling Orders

# Cancel a specific order
exchange.cancel(name="BTC", oid=12345)

# Cancel all open orders for a coin (query the main account, not the API wallet)
open_orders = info.open_orders(account_address)
for order in open_orders:
    if order["coin"] == "BTC":
        exchange.cancel(name="BTC", oid=order["oid"])

Setting Leverage

# Set leverage for BTC to 10x cross margin
exchange.update_leverage(
    leverage=10,
    name="BTC",
    is_cross=True
)

# Set isolated margin at 5x
exchange.update_leverage(
    leverage=5,
    name="ETH",
    is_cross=False
)

取引 API と SDK · 注文を出す · 4/8

Exchange クラス

認証の準備

Exchange クラスは、署名が要る(書き込みの)操作をすべて受け持ちます。署名に使う wallet が必要です。

テストネットだけで使ってください。 この回のサンプルは、どれも実際に注文を出したり、取り消したり、変えたりします。TESTNET_API_URL に向けて、テストネットの API wallet で動かしてください。

import os
import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

# Load the API (agent) wallet key from an environment variable
wallet = eth_account.Account.from_key(os.environ["HL_API_WALLET_KEY"])
account_address = os.environ["HL_ACCOUNT_ADDRESS"]  # your main account

exchange = Exchange(
    wallet,
    base_url=constants.TESTNET_API_URL,
    account_address=account_address,
)
info = Info(constants.TESTNET_API_URL, skip_ws=True)

署名付きの操作は2種類

SDK は2つの方式のどちらかで署名します(署名)。

どのリクエストにも nonce が付きます。SDK は現在時刻のミリ秒を使います。nonce は署名する鍵ごとに管理されます。そのため、bot のプロセスごとに別の API wallet を用意してください(nonce)。

成行注文を出す

API には成行注文という種類がありません。market_open は仲値を読み、slippage(初期値は5%)の分だけ価格をずらして、すぐ約定させる IOC の指値注文 を出します。

# Buy 0.01 BTC at market price (testnet)
result = exchange.market_open(
    name="BTC",
    is_buy=True,
    sz=0.01,       # Size in base asset (BTC)
    slippage=0.01  # Limit price set 1% through the mid
)

print(result)
# {'status': 'ok', 'response': {'type': 'order', 'data': {'statuses': [{'filled': {'totalSz': '0.01', 'avgPx': '...', 'oid': ...}}]}}}

注文の金額は $10 以上にする必要があります。

指値注文を出す

# Place a limit buy for 0.01 BTC at $90,000 (testnet)
result = exchange.order(
    name="BTC",
    is_buy=True,
    sz=0.01,
    limit_px=90000.0,
    order_type={"limit": {"tif": "Gtc"}}  # Good-til-cancelled
)

# The response includes the order ID (oid)
if result["status"] == "ok":
    statuses = result["response"]["data"]["statuses"]
    for s in statuses:
        if "resting" in s:
            print(f"Order placed: oid={s['resting']['oid']}")

有効期間(Time-in-Force)の種類

order_type で、注文がどれだけ有効かを決めます。

TiF 意味 使いどころ
Gtc 取り消すまで有効 指値注文の標準
Ioc 即時約定、残りは取り消し 今すぐ約定させ、残りは取り消す
Alo 板に置くだけ ポストオンリー。約定しそうなら取り消される

order_type のもう1つの形は {"trigger": {"triggerPx": ..., "isMarket": bool, "tpsl": "tp" | "sl"}} です。利確と損切りの注文に使います。

# Post-only order (canceled if it would take liquidity)
exchange.order(
    name="ETH",
    is_buy=True,
    sz=0.1,
    limit_px=3000.0,
    order_type={"limit": {"tif": "Alo"}}
)

# IOC order (fill immediately or cancel)
exchange.order(
    name="ETH",
    is_buy=True,
    sz=0.1,
    limit_px=3100.0,
    order_type={"limit": {"tif": "Ioc"}}
)

注文を取り消す

# Cancel a specific order
exchange.cancel(name="BTC", oid=12345)

# Cancel all open orders for a coin (query the main account, not the API wallet)
open_orders = info.open_orders(account_address)
for order in open_orders:
    if order["coin"] == "BTC":
        exchange.cancel(name="BTC", oid=order["oid"])

レバレッジを設定する

# Set leverage for BTC to 10x cross margin
exchange.update_leverage(
    leverage=10,
    name="BTC",
    is_cross=True
)

# Set isolated margin at 5x
exchange.update_leverage(
    leverage=5,
    name="ETH",
    is_cross=False
)