Hyperliquid

Connector for Hyperliquid perpetuals exchange.

almanak.framework.connectors.hyperliquid

Hyperliquid Connector.

This module provides an adapter for interacting with Hyperliquid perpetual futures exchange, supporting order management, position queries, and L1/L2 message signing.

Hyperliquid is a decentralized perpetual futures exchange supporting: - Long and short positions with up to 50x leverage - Limit and market orders with various time-in-force options - Cross and isolated margin modes - REST API and WebSocket for real-time data

Supported networks: - Mainnet (api.hyperliquid.xyz) - Testnet (api.hyperliquid-testnet.xyz)

Example

from almanak.framework.connectors.hyperliquid import HyperliquidAdapter, HyperliquidConfig

config = HyperliquidConfig( network="mainnet", wallet_address="0x...", private_key="0x...", ) adapter = HyperliquidAdapter(config)

Place a limit 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()

Get position

position = adapter.get_position("ETH")

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.

Attributes:

Name	Type	Description
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.

EIP712Signer

EIP712Signer(
    private_key: str, chain_id: int, is_mainnet: bool = True
)

EIP-712 typed message signer for Hyperliquid.

This class handles the cryptographic signing of messages for both L1 and L2 operations on Hyperliquid. It uses EIP-712 structured data hashing.

The signing process: 1. Construct the EIP-712 typed data structure 2. Hash the domain separator 3. Hash the message struct 4. Sign the combined hash with the private key

Initialize the signer.

Parameters:

Name	Type	Description	Default
private_key	str	Hex-encoded private key (with or without 0x prefix)	required
chain_id	int	Chain ID for EIP-712 domain	required
is_mainnet	bool	Whether this is mainnet (L1) or testnet (L2)	True

sign_l1_action

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

Sign an L1 action for mainnet.

L1 signing uses a specific EIP-712 structure with: - source: The signing wallet address - connectionId: Always the zero address for direct signing - nonce: Unique identifier to prevent replay

Parameters:

Name	Type	Description	Default
action	dict[str, Any]	Action payload	required
nonce	int	Unique nonce	required
vault_address	str | None	Optional vault address	None

Returns:

Type	Description
str	Hex-encoded signature

sign_l2_action

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

Sign an L2 action for testnet.

L2 signing uses a simpler structure that's more gas-efficient for the testnet environment.

Parameters:

Name	Type	Description	Default
action	dict[str, Any]	Action payload	required
nonce	int	Unique nonce	required

Returns:

Type	Description
str	Hex-encoded signature

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.

Parameters:

Name	Type	Description	Default
sign_callback	SignCallback	Function that signs (action, nonce, is_l1) -> signature	required

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...", private_key="0x...", ) adapter = HyperliquidAdapter(config)

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.

Parameters:

Name	Type	Description	Default
config	HyperliquidConfig	Hyperliquid adapter configuration	required
signer	MessageSigner | None	Optional custom message signer (uses EIP712Signer if not provided)	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.

Parameters:

Name	Type	Description	Default
asset	str	Asset symbol (e.g., "ETH", "BTC")	required
is_buy	bool	True for buy, False for sell	required
size	Decimal	Order size in asset units	required
price	Decimal	Limit price (for market orders, used as slippage reference)	required
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

Returns:

Type	Description
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.

Parameters:

Name	Type	Description	Default
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

Returns:

Type	Description
CancelResult	CancelResult indicating success/failure

cancel_all_orders

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

Cancel all open orders.

Parameters:

Name	Type	Description	Default
asset	str | None	Optional asset to filter by	None

Returns:

Type	Description
CancelResult	CancelResult with list of cancelled orders

get_order

get_order(order_id: str) -> HyperliquidOrder | None

Get order by ID.

Parameters:

Name	Type	Description	Default
order_id	str	Order ID to look up	required

Returns:

Type	Description
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.

Parameters:

Name	Type	Description	Default
asset	str | None	Optional asset to filter by	None

Returns:

Type	Description
list[HyperliquidOrder]	List of open orders

get_position

get_position(asset: str) -> HyperliquidPosition | None

Get position for an asset.

Parameters:

Name	Type	Description	Default
asset	str	Asset symbol	required

Returns:

Type	Description
HyperliquidPosition | None	Position details or None if no position

get_all_positions

get_all_positions() -> list[HyperliquidPosition]

Get all open positions.

Returns:

Type	Description
list[HyperliquidPosition]	List of all positions with non-zero size

set_leverage

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

Set leverage for an asset.

Parameters:

Name	Type	Description	Default
asset	str	Asset symbol	required
leverage	int	Target leverage (1-50)	required

Returns:

Type	Description
bool	True if successful

get_leverage

get_leverage(asset: str) -> int

Get current leverage for an asset.

Parameters:

Name	Type	Description	Default
asset	str	Asset symbol	required

Returns:

Type	Description
int	Current leverage setting (default 1)

set_position

set_position(position: HyperliquidPosition) -> None

Set a position for testing.

Parameters:

Name	Type	Description	Default
position	HyperliquidPosition	Position to set	required

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,
    private_key: str | None = None,
    default_slippage_bps: int = 50,
    vault_address: str | None = None,
    agent_address: str | None = None,
)

Configuration for HyperliquidAdapter.

Attributes:

Name	Type	Description
network	str	Target network (mainnet or testnet)
wallet_address	str	Ethereum address for the account
private_key	str | None	Private key for signing (optional, can use external signer)
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.

Attributes:

Name	Type	Description
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.

Attributes:

Name	Type	Description
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

Parameters:

Name	Type	Description	Default
action	dict[str, Any]	Action payload to sign	required
nonce	int	Unique nonce for the action	required
vault_address	str | None	Optional vault address	None

Returns:

Type	Description
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.

Parameters:

Name	Type	Description	Default
action	dict[str, Any]	Action payload to sign	required
nonce	int	Unique nonce for the action	required

Returns:

Type	Description
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.

Attributes:

Name	Type	Description
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.

Attributes:

Name	Type	Description
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.