Hyperliquid¶

Field	Value
Module	`almanak.connectors.hyperliquid`
Protocol kind	Perp
Aliases	N/A

Supported Chains And Intents¶

Chain	Family	Supported Intents
Hyperevm	EVM	`PERP_CLOSE`, `PERP_OPEN`, `PERP_WITHDRAW`

API Reference¶

almanak.connectors.hyperliquid ¶

Hyperliquid perpetuals connector — HyperEVM / CoreWriter.

Executes PERP_OPEN / PERP_CLOSE on HyperEVM (chain id 999) by calling the CoreWriter system contract (0x3333…3333) with a versioned action, submitted as an ordinary gateway ActionBundle transaction. Reads (position, oracle price) go through HyperCore read precompiles via the gateway. The strategy holds no keys and signs nothing — it returns an Intent.

Scope is bounded by the CoreWriter action set and the perp intent vocabulary: market open (IOC) and market close (reduce-only IOC, full/partial). CoreWriter has no set-leverage action and no native trigger orders, so leverage changes and TP/SL are not reachable through this path (they need the L1 EIP-712 API); see compiler.py.

Order encoding lives in sdk.py (byte-exact, szDecimals-aware), market resolution in markets.py (static seed of the liquid majors, fail-closed on unknowns — see the module docstring for the seed vs. dynamic-universe seam).

Note: adapter.py (the abandoned V1-style native-L1 REST simulation) is retained only for its type definitions and is NOT on the execution path — the CoreWriter compiler does not use it.

CancelResult `dataclass` ¶

CancelResult(
    success: bool,
    cancelled_orders: list[str] = list(),
    failed_orders: list[str] = list(),
    error: str | None = None,
    response: dict[str, Any] | None = None,
)

Result of canceling one or more orders.

属性：

名称	类型	描述
`success`	`bool`	Whether operation succeeded
`cancelled_orders`	`list[str]`	List of cancelled order IDs
`failed_orders`	`list[str]`	List of order IDs that failed to cancel
`error`	`str \| None`	Error message if failed
`response`	`dict[str, Any] \| None`	Raw API response

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

ExternalSigner ¶

ExternalSigner(sign_callback: SignCallback)

External signer that delegates to a callback.

This allows using hardware wallets, custodians, or other external signing solutions.

Initialize with signing callback.

参数：

名称	类型	描述	默认
`sign_callback`	`SignCallback`	Function that signs (action, nonce, is_l1) -> signature	必需

sign_l1_action ¶

sign_l1_action(
    action: dict[str, Any],
    nonce: int,
    vault_address: str | None = None,
) -> str

Sign an L1 action using external signer.

sign_l2_action ¶

sign_l2_action(action: dict[str, Any], nonce: int) -> str

Sign an L2 action using external signer.

HyperliquidAdapter ¶

HyperliquidAdapter(
    config: HyperliquidConfig,
    signer: MessageSigner | None = None,
)

Adapter for Hyperliquid perpetual futures exchange.

This adapter provides methods for: - Placing limit and market orders - Canceling orders by ID or client ID - Querying positions and open orders - Managing leverage and margin settings

Example

config = HyperliquidConfig( network="mainnet", wallet_address="0x...", ) adapter = HyperliquidAdapter(config, signer=ExternalSigner(sign_callback))

Place a limit buy order¶

result = adapter.place_order( asset="ETH", is_buy=True, size=Decimal("0.1"), price=Decimal("2000"), )

Check open orders¶

orders = adapter.get_open_orders()

Cancel order¶

cancel_result = adapter.cancel_order(order_id=result.order_id)

Initialize the adapter.

参数：

名称	类型	描述	默认
`config`	`HyperliquidConfig`	Hyperliquid adapter configuration	必需
`signer`	`MessageSigner \| None`	Optional message signer (e.g. ExternalSigner). The adapter never signs in-process; without a signer, write operations carry an inert placeholder signature (simulation only).	`None`

place_order ¶

place_order(
    asset: str,
    is_buy: bool,
    size: Decimal,
    price: Decimal,
    order_type: HyperliquidOrderType = HyperliquidOrderType.LIMIT,
    time_in_force: HyperliquidTimeInForce = HyperliquidTimeInForce.GTC,
    reduce_only: bool = False,
    client_id: str | None = None,
    slippage_bps: int | None = None,
) -> OrderResult

Place a new order.

参数：

名称	类型	描述	默认
`asset`	`str`	Asset symbol (e.g., "ETH", "BTC")	必需
`is_buy`	`bool`	True for buy, False for sell	必需
`size`	`Decimal`	Order size in asset units	必需
`price`	`Decimal`	Limit price (for market orders, used as slippage reference)	必需
`order_type`	`HyperliquidOrderType`	Order type (limit or market)	`LIMIT`
`time_in_force`	`HyperliquidTimeInForce`	Time in force option	`GTC`
`reduce_only`	`bool`	Whether order can only reduce position	`False`
`client_id`	`str \| None`	Optional client-assigned order ID	`None`
`slippage_bps`	`int \| None`	Slippage tolerance for market orders	`None`

返回：

类型	描述
`OrderResult`	OrderResult with order details

cancel_order ¶

cancel_order(
    order_id: str | None = None,
    client_id: str | None = None,
    asset: str | None = None,
) -> CancelResult

Cancel an existing order.

参数：

名称	类型	描述	默认
`order_id`	`str \| None`	Exchange-assigned order ID	`None`
`client_id`	`str \| None`	Client-assigned order ID	`None`
`asset`	`str \| None`	Asset symbol (required with client_id)	`None`

返回：

类型	描述
`CancelResult`	CancelResult indicating success/failure

cancel_all_orders ¶

cancel_all_orders(asset: str | None = None) -> CancelResult

Cancel all open orders.

参数：

名称	类型	描述	默认
`asset`	`str \| None`	Optional asset to filter by	`None`

返回：

类型	描述
`CancelResult`	CancelResult with list of cancelled orders

get_order ¶

get_order(order_id: str) -> HyperliquidOrder | None

Get order by ID.

参数：

名称	类型	描述	默认
`order_id`	`str`	Order ID to look up	必需

返回：

类型	描述
`HyperliquidOrder \| None`	Order details or None if not found

get_open_orders ¶

get_open_orders(
    asset: str | None = None,
) -> list[HyperliquidOrder]

Get all open orders.

参数：

名称	类型	描述	默认
`asset`	`str \| None`	Optional asset to filter by	`None`

返回：

类型	描述
`list[HyperliquidOrder]`	List of open orders

get_position ¶

get_position(asset: str) -> HyperliquidPosition | None

Get position for an asset.

参数：

名称	类型	描述	默认
`asset`	`str`	Asset symbol	必需

返回：

类型	描述
`HyperliquidPosition \| None`	Position details or None if no position

get_all_positions ¶

get_all_positions() -> list[HyperliquidPosition]

Get all open positions.

返回：

类型	描述
`list[HyperliquidPosition]`	List of all positions with non-zero size

set_leverage ¶

set_leverage(asset: str, leverage: int) -> bool

Set leverage for an asset.

参数：

名称	类型	描述	默认
`asset`	`str`	Asset symbol	必需
`leverage`	`int`	Target leverage (1-50)	必需

返回：

类型	描述
`bool`	True if successful

get_leverage ¶

get_leverage(asset: str) -> int

Get current leverage for an asset.

参数：

名称	类型	描述	默认
`asset`	`str`	Asset symbol	必需

返回：

类型	描述
`int`	Current leverage setting (default 1)

set_position ¶

set_position(position: HyperliquidPosition) -> None

Set a position for testing.

参数：

名称	类型	描述	默认
`position`	`HyperliquidPosition`	Position to set	必需

clear_positions ¶

clear_positions() -> None

Clear all positions.

clear_orders ¶

clear_orders() -> None

Clear all orders.

clear_all ¶

clear_all() -> None

Clear all state.

HyperliquidConfig `dataclass` ¶

HyperliquidConfig(
    network: str,
    wallet_address: str,
    default_slippage_bps: int = 50,
    vault_address: str | None = None,
    agent_address: str | None = None,
)

Configuration for HyperliquidAdapter.

Holds no secrets: signing is delegated through MessageSigner (see module docstring), so there is no private-key field here.

属性：

名称	类型	描述
`network`	`str`	Target network (mainnet or testnet)
`wallet_address`	`str`	Ethereum address for the account
`default_slippage_bps`	`int`	Default slippage tolerance in basis points (default 50 = 0.5%)
`vault_address`	`str \| None`	Optional vault address for vault trading
`agent_address`	`str \| None`	Optional agent address for delegated trading

api_url `property` ¶

api_url: str

Get API URL for configured network.

ws_url `property` ¶

ws_url: str

Get WebSocket URL for configured network.

chain_id `property` ¶

chain_id: int

Get chain ID for configured network.

eip712_domain `property` ¶

eip712_domain: dict[str, Any]

Get EIP-712 domain for configured network.

__post_init__ ¶

__post_init__() -> None

Validate configuration.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

HyperliquidMarginMode ¶

Bases: Enum

Margin mode options.

HyperliquidNetwork ¶

Bases: Enum

Hyperliquid network environments.

HyperliquidOrder `dataclass` ¶

HyperliquidOrder(
    order_id: str,
    client_id: str | None,
    asset: str,
    side: HyperliquidOrderSide,
    size: Decimal,
    price: Decimal,
    order_type: HyperliquidOrderType = HyperliquidOrderType.LIMIT,
    time_in_force: HyperliquidTimeInForce = HyperliquidTimeInForce.GTC,
    reduce_only: bool = False,
    status: HyperliquidOrderStatus = HyperliquidOrderStatus.OPEN,
    filled_size: Decimal = Decimal("0"),
    avg_fill_price: Decimal | None = None,
    created_at: datetime = (lambda: datetime.now(UTC))(),
    updated_at: datetime = (lambda: datetime.now(UTC))(),
)

Represents a Hyperliquid order.

属性：

名称	类型	描述
`order_id`	`str`	Exchange-assigned order ID
`client_id`	`str \| None`	Client-assigned order ID (cloid)
`asset`	`str`	Asset symbol
`side`	`HyperliquidOrderSide`	Order side (buy/sell)
`size`	`Decimal`	Order size
`price`	`Decimal`	Limit price
`order_type`	`HyperliquidOrderType`	Order type (limit/market)
`time_in_force`	`HyperliquidTimeInForce`	Time in force option
`reduce_only`	`bool`	Whether order can only reduce position
`status`	`HyperliquidOrderStatus`	Current order status
`filled_size`	`Decimal`	Amount already filled
`avg_fill_price`	`Decimal \| None`	Average fill price
`created_at`	`datetime`	Order creation timestamp
`updated_at`	`datetime`	Last update timestamp

remaining_size `property` ¶

remaining_size: Decimal

Get remaining unfilled size.

is_buy `property` ¶

is_buy: bool

Check if order is a buy.

is_sell `property` ¶

is_sell: bool

Check if order is a sell.

is_open `property` ¶

is_open: bool

Check if order is still open.

is_filled `property` ¶

is_filled: bool

Check if order is fully filled.

fill_percentage `property` ¶

fill_percentage: Decimal

Get fill percentage.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> HyperliquidOrder

Create from dictionary.

HyperliquidOrderSide ¶

Bases: Enum

Order side (buy/sell).

HyperliquidOrderStatus ¶

Bases: Enum

Order status values.

HyperliquidOrderType ¶

Bases: Enum

Hyperliquid order types.

HyperliquidPosition `dataclass` ¶

HyperliquidPosition(
    asset: str,
    size: Decimal,
    entry_price: Decimal,
    mark_price: Decimal = Decimal("0"),
    liquidation_price: Decimal | None = None,
    unrealized_pnl: Decimal = Decimal("0"),
    realized_pnl: Decimal = Decimal("0"),
    margin_used: Decimal = Decimal("0"),
    leverage: Decimal = Decimal("1"),
    margin_mode: HyperliquidMarginMode = HyperliquidMarginMode.CROSS,
    max_leverage: int = 50,
    last_updated: datetime = (lambda: datetime.now(UTC))(),
)

Represents an open Hyperliquid position.

属性：

名称	类型	描述
`asset`	`str`	Asset symbol (e.g., "ETH")
`size`	`Decimal`	Position size (positive for long, negative for short)
`entry_price`	`Decimal`	Average entry price
`mark_price`	`Decimal`	Current mark price
`liquidation_price`	`Decimal \| None`	Estimated liquidation price
`unrealized_pnl`	`Decimal`	Unrealized profit/loss
`realized_pnl`	`Decimal`	Realized profit/loss
`margin_used`	`Decimal`	Margin allocated to position
`leverage`	`Decimal`	Current leverage
`margin_mode`	`HyperliquidMarginMode`	Cross or isolated margin
`max_leverage`	`int`	Maximum allowed leverage for asset
`last_updated`	`datetime`	Timestamp of last update

side `property` ¶

side: HyperliquidPositionSide

Get position side.

is_long `property` ¶

is_long: bool

Check if position is long.

is_short `property` ¶

is_short: bool

Check if position is short.

notional_value `property` ¶

notional_value: Decimal

Get notional value of position.

net_pnl `property` ¶

net_pnl: Decimal

Get net PnL (realized + unrealized).

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> HyperliquidPosition

Create from dictionary.

HyperliquidPositionSide ¶

Bases: Enum

Position side (long/short).

HyperliquidTimeInForce ¶

Bases: Enum

Time in force options for orders.

MessageSigner ¶

Bases: Protocol

Protocol for message signing implementations.

sign_l1_action ¶

sign_l1_action(
    action: dict[str, Any],
    nonce: int,
    vault_address: str | None = None,
) -> str

Sign an L1 action.

L1 actions are used for mainnet and include: - Order placement - Order cancellation - Withdrawal requests

参数：

名称	类型	描述	默认
`action`	`dict[str, Any]`	Action payload to sign	必需
`nonce`	`int`	Unique nonce for the action	必需
`vault_address`	`str \| None`	Optional vault address	`None`

返回：

类型	描述
`str`	Hex-encoded signature

sign_l2_action ¶

sign_l2_action(action: dict[str, Any], nonce: int) -> str

Sign an L2 action.

L2 actions are used for testnet and some mainnet operations. The signing scheme is slightly different from L1.

参数：

名称	类型	描述	默认
`action`	`dict[str, Any]`	Action payload to sign	必需
`nonce`	`int`	Unique nonce for the action	必需

返回：

类型	描述
`str`	Hex-encoded signature

OrderResult `dataclass` ¶

OrderResult(
    success: bool,
    order_id: str | None = None,
    client_id: str | None = None,
    order: HyperliquidOrder | None = None,
    error: str | None = None,
    response: dict[str, Any] | None = None,
)

Result of placing or canceling an order.

属性：

名称	类型	描述
`success`	`bool`	Whether operation succeeded
`order_id`	`str \| None`	Order ID if successful
`client_id`	`str \| None`	Client-assigned order ID
`order`	`HyperliquidOrder \| None`	Created/affected order object
`error`	`str \| None`	Error message if failed
`response`	`dict[str, Any] \| None`	Raw API response

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

SignedAction `dataclass` ¶

SignedAction(
    action: dict[str, Any],
    signature: str,
    nonce: int,
    vault_address: str | None = None,
)

A signed action ready for submission to Hyperliquid.

属性：

名称	类型	描述
`action`	`dict[str, Any]`	The action payload
`signature`	`str`	EIP-712 signature
`nonce`	`int`	Nonce used for signing
`vault_address`	`str \| None`	Optional vault address

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

PerpMarket `dataclass` ¶

PerpMarket(
    symbol: str,
    asset_index: int,
    sz_decimals: int,
    max_leverage: int,
)

A resolved Hyperliquid perp market.

属性：

名称	类型	描述
`symbol`	`str`	Canonical base symbol (e.g. `"BTC"`).
`asset_index`	`int`	HyperCore perp index (the `uint32` a CoreWriter order encodes).
`sz_decimals`	`int`	Size decimal places — drives price/size tick rounding.
`max_leverage`	`int`	Max leverage the venue allows for this asset (advisory).

normalize_symbol ¶

normalize_symbol(market: str) -> str

Normalise a market string to a bare base symbol.

"btc-usd" / "BTC/USD" / "BTC-PERP" / "BTC" → "BTC". Preserves Hyperliquid's k-prefixed thousands symbols (kPEPE) by only upper-casing when no exact-case seed entry exists.

resolve_market ¶

resolve_market(
    market: str,
    *,
    universe: dict[str, PerpMarket] | None = None,
) -> PerpMarket

Resolve a market symbol to a :class:PerpMarket, fail-closed on unknown.

参数：

名称	类型	描述	默认
`market`	`str`	A market symbol (`"BTC"`, `"BTC-USD"`, …). Resolution is by normalized symbol against the dynamic universe (when supplied) or the static seed; bare index strings are not parsed (fail-closed on unknown).	必需
`universe`	`dict[str, PerpMarket] \| None`	Optional symbol→:class:`PerpMarket` map from a dynamic source (the future gateway universe capability). Tried before the static seed; the seed is the fallback. When `None` (today), only the seed is consulted.	`None`

引发：

类型	描述
`ValueError`	If the symbol is not resolvable — the connector never guesses an index (trading the wrong asset is the failure mode this prevents).

seeded_symbols ¶

seeded_symbols() -> frozenset[str]

The set of symbols the static seed can resolve today.

getattr ¶

__getattr__(name: str) -> Any

PEP 562 lazy attribute access.

Hyperliquid¶

Supported Chains And Intents¶

API Reference¶

almanak.connectors.hyperliquid ¶

CancelResult dataclass ¶

to_dict ¶

ExternalSigner ¶

sign_l1_action ¶

sign_l2_action ¶

HyperliquidAdapter ¶

Place a limit buy order¶

Check open orders¶

Cancel order¶

place_order ¶

cancel_order ¶

cancel_all_orders ¶

get_order ¶

get_open_orders ¶

get_position ¶

get_all_positions ¶

set_leverage ¶

get_leverage ¶

set_position ¶

clear_positions ¶

clear_orders ¶

clear_all ¶

HyperliquidConfig dataclass ¶

api_url property ¶

ws_url property ¶

chain_id property ¶

eip712_domain property ¶

__post_init__ ¶

to_dict ¶

HyperliquidMarginMode ¶

HyperliquidNetwork ¶

HyperliquidOrder dataclass ¶

remaining_size property ¶

is_buy property ¶

is_sell property ¶

is_open property ¶

is_filled property ¶

fill_percentage property ¶

to_dict ¶

from_dict classmethod ¶

HyperliquidOrderSide ¶

HyperliquidOrderStatus ¶

HyperliquidOrderType ¶

HyperliquidPosition dataclass ¶

side property ¶

is_long property ¶

is_short property ¶

notional_value property ¶

net_pnl property ¶

to_dict ¶

from_dict classmethod ¶

HyperliquidPositionSide ¶

HyperliquidTimeInForce ¶

MessageSigner ¶

sign_l1_action ¶

sign_l2_action ¶

OrderResult dataclass ¶

to_dict ¶

SignedAction dataclass ¶

to_dict ¶

PerpMarket dataclass ¶

normalize_symbol ¶

resolve_market ¶

seeded_symbols ¶

__getattr__ ¶

CancelResult `dataclass` ¶

HyperliquidConfig `dataclass` ¶

api_url `property` ¶

ws_url `property` ¶

chain_id `property` ¶

eip712_domain `property` ¶

HyperliquidOrder `dataclass` ¶

remaining_size `property` ¶

is_buy `property` ¶

is_sell `property` ¶

is_open `property` ¶

is_filled `property` ¶

fill_percentage `property` ¶

from_dict `classmethod` ¶

HyperliquidPosition `dataclass` ¶

side `property` ¶

is_long `property` ¶

is_short `property` ¶

notional_value `property` ¶

net_pnl `property` ¶

from_dict `classmethod` ¶

OrderResult `dataclass` ¶

SignedAction `dataclass` ¶

PerpMarket `dataclass` ¶

getattr ¶