Exchange¤

hl.Exchange ¤

Exchange(
    *,
    transport: BaseTransport,
    universe: Universe,
    account: Account | None = None,
)

The Exchange class provides methods to interact with the /exchange endpoint.

The methods interact with onchain assets and manages orders on the exchange.

Parameters:

Name	Type	Description	Default
`transport`	`BaseTransport`	The transport to use to make the requests.	required
`universe`	`Universe`	The universe to use for the exchange.	required
`account`	`Account \| None`	The account to use for the exchange. Defaults to None.	`None`

Returns:

Type	Description
`Exchange`	The Exchange instance.

Methods:

Name	Description
`adjust_margin`	Adjust the isolated margin for a given asset to a specific leverage ratio.
`approve_agent`	Approve an agent (also known as an API Wallet).
`approve_builder`	Approve a builder with a maximum fee rate.
`cancel_order`	Cancel an order by its oid.
`cancel_order_by_id`	Cancel an order by its client order id.
`cancel_orders`	Cancel multiple orders by their oid.
`cancel_orders_by_id`	Cancel one or more orders by their client order id.
`cancel_twap`	Cancel a TWAP order.
`create_sub_account`	Create a subaccount.
`create_vault`	Create a vault.
`delegate_tokens`	Delegate or undelegate HYPE tokens to or from a validator.
`modify_order`	Modify an order.
`modify_orders`	Modify multiple orders.
`place_order`	Place a single order.
`place_orders`	Place multiple orders.
`place_twap`	Place a TWAP order.
`register_referrer`	Register a referrer.
`reserve_weight`	Reserve additional request weight which counts against the rate limit.
`schedule_cancellation`	Schedule a cancel-all operation at a future time.
`send_spot`	Send a spot asset to another address.
`send_usd`	Send USDC to another address.
`set_referrer`	Set a referrer.
`stake_tokens`	Stake HYPE tokens.
`transfer_account_funds`	Transfer USDC between a user's main account and a subaccount.
`transfer_tokens`	Transfer a token from a user's spot wallet to their perp wallet and vice versa.
`transfer_usd`	Transfer USDC between a user's spot wallet and their perp wallet and vice versa.
`transfer_vault_funds`	Transfer USDC to or from a vault.
`unstake_tokens`	Unstake HYPE tokens.
`update_leverage`	Update the leverage for a given asset.
`update_margin`	Update the isolated margin for a given asset.
`withdraw_funds`	Withdraw USDC via Arbitrum.

adjust_margin `async` ¤

adjust_margin(
    *, asset: int | str, leverage: Decimal
) -> Result[TopUpIsolatedOnlyMarginResponse, ApiError]

Adjust the isolated margin for a given asset to a specific leverage ratio.

This function allows you to target a specific leverage ratio instead of a specific USDC amount.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to adjust the isolated margin for.	required
`leverage`	`Decimal`	The leverage to set for the asset.	required

Returns:

Type	Description
`Result[TopUpIsolatedOnlyMarginResponse, ApiError]`	A Result containing the response from adjusting the isolated margin.

approve_agent `async` ¤

approve_agent(
    *,
    agent: str,
    name: str | None = None,
    account: Account | None = None,
) -> Result[ApproveAgentResponse, ApiError]

Approve an agent (also known as an API Wallet).

POST /exchange

Parameters:

Name	Type	Description	Default
`agent`	`str`	The address of the agent to approve.	required
`name`	`str \| None`	The name of the agent to approve.	`None`
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[ApproveAgentResponse, ApiError]`	A Result containing the response from approving the agent.

approve_builder `async` ¤

approve_builder(
    *,
    builder: str,
    max_fee_rate: Decimal,
    account: Account | None = None,
) -> Result[ApproveBuilderFeeResponse, ApiError]

Approve a builder with a maximum fee rate.

POST /exchange

Parameters:

Name	Type	Description	Default
`builder`	`str`	The address of the builder to approve.	required
`max_fee_rate`	`Decimal`	The maximum fee rate to approve for the builder. Decimal percentage (e.g. 0.01 for 1%) must be between 0 and 1.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[ApproveBuilderFeeResponse, ApiError]`	A Result containing the response from approving the builder.

cancel_order `async` ¤

cancel_order(
    *,
    asset: int | str,
    order_id: int,
    account: Account | None = None,
) -> Result[CancelResponse, ApiError]

Cancel an order by its oid.

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to cancel the order on.	required
`order_id`	`int`	The oid of the order to cancel.	required
`account`	`Account \| None`	The account to use for the order. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[CancelResponse, ApiError]`	A Result containing the response from cancelling the order.

cancel_order_by_id `async` ¤

cancel_order_by_id(
    asset: int | str, client_order_id: Cloid | str
) -> Result[CancelByCloidResponse, ApiError]

Cancel an order by its client order id.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to cancel the order on.	required
`client_order_id`	`Cloid \| str`	The client order id to cancel the order by.	required

Returns:

Type	Description
`Result[CancelByCloidResponse, ApiError]`	A Result containing the response from cancelling the order.

cancel_orders `async` ¤

cancel_orders(
    *,
    cancel_requests: Sequence[CancelParams],
    account: Account | None = None,
) -> Result[CancelResponse, ApiError]

Cancel multiple orders by their oid.

POST /exchange

Parameters:

Name	Type	Description	Default
`cancel_requests`	`list[OrderCancelParams]`	The orders to cancel.	required
`account`	`Account \| None`	The account to use for the order. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[CancelResponse, ApiError]`	A Result containing the response from cancelling the orders.

cancel_orders_by_id `async` ¤

cancel_orders_by_id(
    cancel_requests: list[CancelByCloidParams],
) -> Result[CancelByCloidResponse, ApiError]

Cancel one or more orders by their client order id.

POST /exchange

Parameters:

Name	Type	Description	Default
`cancel_requests`	`list[CancelByCloidParams]`	The orders to cancel.	required

Returns:

Type	Description
`Result[CancelByCloidResponse, ApiError]`	A Result containing the response from cancelling the orders.

cancel_twap `async` ¤

cancel_twap(
    *,
    asset: str | int,
    twap_id: int,
    account: Account | None = None,
) -> Result[TwapCancelResponse, ApiError]

Cancel a TWAP order.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`str \| int`	The asset id or name of the twap order to cancel.	required
`twap_id`	`int`	The id of the TWAP order to cancel.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[TwapCancelResponse, ApiError]`	A Result containing the response from canceling the TWAP order.

create_sub_account `async` ¤

create_sub_account(
    name: str,
) -> Result[CreateSubAccountResponse, ApiError]

Create a subaccount.

POST /exchange

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the subaccount to create.	required

Returns:

Type	Description
`Result[CreateSubAccountResponse, ApiError]`	A Result containing the response from creating the subaccount.

create_vault `async` ¤

create_vault(
    name: str, description: str, initial_usd: Decimal
) -> Result[CreateVaultResponse, ApiError]

Create a vault.

POST /exchange

Returns:

Type	Description
`Result[CreateVaultResponse, ApiError]`	A Result containing the response from creating the vault.

delegate_tokens `async` ¤

delegate_tokens(
    *,
    validator: str,
    amount: Decimal,
    is_undelegate: bool,
    account: Account | None = None,
) -> Result[TokenDelegateResponse, ApiError]

Delegate or undelegate HYPE tokens to or from a validator.

Note that delegations to a particular validator have a lockup duration of 1 day.

POST /exchange

Parameters:

Name	Type	Description	Default
`validator`	`str`	The address to delegate to or to undelegate from.	required
`amount`	`Decimal`	The amount of HYPE to delegate or undelegate.	required
`is_undelegate`	`bool`	Whether the action is to undelegate or delegate an amount.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[TokenDelegateResponse, ApiError]`	A Result containing the response from delegating to or undelegating from staking.

modify_order `async` ¤

modify_order(
    *,
    order_id: int | Cloid,
    asset: int | str,
    is_buy: bool,
    size: Decimal,
    limit_price: Decimal,
    order_type: OrderType,
    reduce_only: bool = False,
) -> Result[ModifyResponse, ApiError]

Modify an order.

POST /exchange

Parameters:

Name	Type	Description	Default
`order_id`	`int \| Cloid`	The oid of the order to modify.	required
`asset`	`int \| str`	The asset to modify the order to.	required
`is_buy`	`bool`	Whether the order is a buy order.	required
`size`	`Decimal`	The size of the order.	required
`limit_price`	`Decimal`	The limit price of the order.	required
`order_type`	`OrderType`	The type (limit, trigger) of order to modify.	required
`reduce_only`	`bool`	Whether the order is a reduce-only order.	`False`

Returns:

Type	Description
`Result[ModifyResponse, ApiError]`	A Result containing the response from modifying the order.

modify_orders `async` ¤

modify_orders(
    modify_requests: list[ModifyParams],
) -> Result[BatchModifyResponse, ApiError]

Modify multiple orders.

POST /exchange

Parameters:

Name	Type	Description	Default
`modify_requests`	`list[ModifyParams]`	The orders to modify.	required

Returns:

Type	Description
`Result[BatchModifyResponse, ApiError]`	A Result containing the response from modifying the orders.

place_order `async` ¤

place_order(
    *,
    asset: int | str,
    is_buy: bool,
    size: Decimal,
    limit_price: Decimal,
    order_type: OrderType,
    reduce_only: bool = False,
    cloid: Cloid | None = None,
    builder: BuilderOptions | None = None,
    account: Account | None = None,
) -> Result[OrderResponse, ApiError]

Place a single order.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to place the order on.	required
`is_buy`	`bool`	Whether the order is a buy order.	required
`size`	`Decimal`	The size of the order.	required
`limit_price`	`Decimal`	The limit price of the order.	required
`order_type`	`OrderType`	The type (limit, trigger) of order to place.	required
`reduce_only`	`bool`	Whether the order is a reduce-only order.	`False`
`cloid`	`Cloid \| None`	The cloid to use for the order. Defaults to None.	`None`
`builder`	`BuilderOptions \| None`	The builder options to use for the order. Defaults to None.	`None`
`account`	`Account \| None`	The account to use for the order. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[OrderResponse, ApiError]`	A Result containing the response from placing the order.

place_orders `async` ¤

place_orders(
    *,
    order_requests: list[OrderParams],
    grouping: Grouping = "na",
    builder: BuilderOptions | None = None,
    account: Account | None = None,
) -> Result[OrderResponse, ApiError]

Place multiple orders.

POST /exchange

Parameters:

Name	Type	Description	Default
`order_requests`	`list[OrderParams]`	The orders to place.	required
`grouping`	`Grouping`	The grouping to use for the orders. Defaults to "na".	`'na'`
`builder`	`BuilderOptions \| None`	The builder options to use for the orders. Defaults to None.	`None`
`account`	`Account \| None`	The account to use for the orders. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[OrderResponse, ApiError]`	A Result containing the response from placing the orders.

place_twap `async` ¤

place_twap(
    *,
    asset: int | str,
    size: Decimal,
    minutes: int,
    randomize: bool,
    is_buy: bool,
    reduce_only: bool = False,
    account: Account | None = None,
) -> Result[TwapOrderResponse, ApiError]

Place a TWAP order.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to place the TWAP order on.	required
`size`	`Decimal`	The size of the TWAP order.	required
`minutes`	`int`	The number of minutes this TWAP order should run for.	required
`randomize`	`bool`	Whether to randomize the TWAP order.	required
`is_buy`	`bool`	Whether the TWAP order is a buy order.	required
`reduce_only`	`bool`	Whether the order is a reduce-only order.	`False`
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[TwapOrderResponse, ApiError]`	A Result containing the response from placing a TWAP order.

register_referrer `async` ¤

register_referrer(
    *, code: str, account: Account | None = None
) -> Result[RegisterReferrerResponse, ApiError]

Register a referrer.

POST /exchange

Parameters:

Name	Type	Description	Default
`code`	`str`	The code of the referrer to register.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[RegisterReferrerResponse, ApiError]`	A Result containing the response from registering the referrer.

reserve_weight `async` ¤

reserve_weight(
    *, weight: int, account: Account | None = None
) -> Result[ReserveRequestWeightResponse, ApiError]

Reserve additional request weight which counts against the rate limit.

Instead of trading to increase the address based rate limits, this action allows reserving additional actions for 0.0005 USDC per request

Parameters:

Name	Type	Description	Default
`weight`	`int`	The number of actions for which to purchase request weight.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[ReserveRequestWeightResponse, ApiError]`	A Result containing the response from reserving additional request weight.

schedule_cancellation `async` ¤

schedule_cancellation(
    *,
    time: int | datetime | date | None = None,
    account: Account | None = None,
) -> Result[ScheduleCancelResponse, ApiError]

Schedule a cancel-all operation at a future time.

Schedules a time (in UTC millis) to cancel all open orders. The time must be at least 5 seconds after the current time. Once the time comes, all open orders will be canceled and a trigger count will be incremented. The max number of triggers per day is 10. This trigger count is reset at 00:00 UTC.

Parameters:

Name	Type	Description	Default
`time`	`int \| datetime \| date \| None`	if time is not None, then set the cancel time in the future. If None, then unsets any cancel time in the future.	`None`
`account`	`Account \| None`	The account to use for the cancel. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[ScheduleCancelResponse, ApiError]`	A Result containing the response from scheduling the cancel.

send_spot `async` ¤

send_spot(
    *,
    asset: int | str,
    amount: Decimal,
    destination: str,
    account: Account | None = None,
) -> Result[SpotSendResponse, ApiError]

Send a spot asset to another address.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to send.	required
`amount`	`Decimal`	The amount of the coin to send.	required
`destination`	`str`	The address to send the coin to.	required
`account`	`Account \| None`	The account to use for the request from which tokens are sent. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[SpotSendResponse, ApiError]`	A Result containing the response from sending the spot asset.

send_usd `async` ¤

send_usd(
    *,
    amount: Decimal,
    destination: str,
    account: Account | None = None,
) -> Result[UsdSendResponse, ApiError]

Send USDC to another address.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of USDC to send.	required
`destination`	`str`	The address to send the USDC to.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[UsdSendResponse, ApiError]`	A Result containing the response from sending the USDC.

set_referrer `async` ¤

set_referrer(
    code: str,
) -> Result[SetReferrerResponse, ApiError]

Set a referrer.

POST /exchange

Parameters:

Name	Type	Description	Default
`code`	`str`	The code of the referrer to set.	required

Returns:

Type	Description
`Result[SetReferrerResponse, ApiError]`	A Result containing the response from setting the referrer.

stake_tokens `async` ¤

stake_tokens(
    *, amount: Decimal, account: Account | None = None
) -> Result[DepositStakingResponse, ApiError]

Stake HYPE tokens.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of HYPE to stake.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[DepositStakingResponse, ApiError]`	A Result containing the response from staking HYPE tokens.

transfer_account_funds `async` ¤

transfer_account_funds(
    *,
    amount: Decimal,
    address: str,
    is_deposit: bool,
    account: Account | None = None,
) -> Result[SubAccountTransferResponse, ApiError]

Transfer USDC between a user's main account and a subaccount.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of USDC to transfer.	required
`address`	`str`	The address of the subaccount to transfer the USDC to.	required
`is_deposit`	`bool`	Whether to transfer the USDC to the subaccount (True) or to the main account (False).	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[SubAccountTransferResponse, ApiError]`	A Result containing the response from transferring the USDC.

transfer_tokens `async` ¤

transfer_tokens(
    *,
    amount: Decimal,
    to_perp: bool,
    dex: str,
    token: str,
    account: Account | None = None,
) -> Result[PerpDexClassTransferResponse, ApiError]

Transfer a token from a user's spot wallet to their perp wallet and vice versa.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of the token to transfer.	required
`to_perp`	`bool`	Whether to transfer the token to the perp wallet (True) or to the spot wallet (False).	required
`dex`	`str`	The name of the dex to transfer the token from.	required
`token`	`str`	The name of the token to transfer.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[PerpDexClassTransferResponse, ApiError]`	A Result containing the response from transferring the token.

transfer_usd `async` ¤

transfer_usd(
    *,
    amount: Decimal,
    to_perp: bool,
    account: Account | None = None,
) -> Result[UsdClassTransferResponse, ApiError]

Transfer USDC between a user's spot wallet and their perp wallet and vice versa.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of USDC to transfer.	required
`to_perp`	`bool`	Whether to transfer the USDC to the perp wallet (True) or to the spot wallet (False).	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[UsdClassTransferResponse, ApiError]`	A Result containing the response from transferring the USDC.

transfer_vault_funds `async` ¤

transfer_vault_funds(
    *,
    vault: str,
    amount: Decimal,
    is_deposit: bool,
    account: Account | None = None,
) -> Result[VaultTransferResponse, ApiError]

Transfer USDC to or from a vault.

POST /exchange

Parameters:

Name	Type	Description	Default
`vault`	`str`	The address of the vault to transfer USDC to or from.	required
`amount`	`Decimal`	The amount of USDC to transfer.	required
`is_deposit`	`bool`	Whether to transfer USDC to the vault (True) or from the vault (False).	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[VaultTransferResponse, ApiError]`	A Result containing the response from transferring USDC to or from the vault.

unstake_tokens `async` ¤

unstake_tokens(
    *, amount: Decimal, account: Account | None = None
) -> Result[WithdrawStakingResponse, ApiError]

Unstake HYPE tokens.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of HYPE to unstake.	required
`account`	`Account \| None`	The account to use for the request. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[WithdrawStakingResponse, ApiError]`	A Result containing the response from unstaking HYPE tokens.

update_leverage `async` ¤

update_leverage(
    *,
    asset: int | str,
    leverage: int,
    margin_mode: Literal["cross", "isolated"],
) -> Result[UpdateLeverageResponse, ApiError]

Update the leverage for a given asset.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to update the leverage for.	required
`leverage`	`int`	The leverage to set for the asset.	required
`margin_mode`	`Literal['cross', 'isolated']`	Either "cross" or "isolated".	required

Returns:

Type	Description
`Result[UpdateLeverageResponse, ApiError]`	A Result containing the response from updating the leverage.

update_margin `async` ¤

update_margin(
    *, asset: int | str, amount: Decimal
) -> Result[UpdateIsolatedMarginResponse, ApiError]

Update the isolated margin for a given asset.

POST /exchange

Parameters:

Name	Type	Description	Default
`asset`	`int \| str`	The asset to update the isolated margin for.	required
`amount`	`Decimal`	The amount to remove from or to add to the isolated margin.	required

Returns:

Type	Description
`Result[UpdateIsolatedMarginResponse, ApiError]`	A Result containing the response from updating the isolated margin.

withdraw_funds `async` ¤

withdraw_funds(
    *,
    amount: Decimal,
    destination: str,
    account: Account | None = None,
) -> Result[WithdrawResponse, ApiError]

Withdraw USDC via Arbitrum.

POST /exchange

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	The amount of USDC to withdraw.	required
`destination`	`str`	The address to withdraw the USDC to.	required
`account`	`Account \| None`	The account to use for the request from which USDC are sent. Defaults to the class-level account.	`None`

Returns:

Type	Description
`Result[WithdrawResponse, ApiError]`	A Result containing the response from withdrawing the USDC.

Exchange¤

hl.Exchange ¤

adjust_margin async ¤

approve_agent async ¤

approve_builder async ¤

cancel_order async ¤

cancel_order_by_id async ¤

cancel_orders async ¤

cancel_orders_by_id async ¤

cancel_twap async ¤

create_sub_account async ¤

create_vault async ¤

delegate_tokens async ¤

modify_order async ¤

modify_orders async ¤

place_order async ¤

place_orders async ¤

place_twap async ¤

register_referrer async ¤

reserve_weight async ¤

schedule_cancellation async ¤

send_spot async ¤

send_usd async ¤

set_referrer async ¤

stake_tokens async ¤

transfer_account_funds async ¤

transfer_tokens async ¤

transfer_usd async ¤

transfer_vault_funds async ¤

unstake_tokens async ¤

update_leverage async ¤

update_margin async ¤

withdraw_funds async ¤

adjust_margin `async` ¤

approve_agent `async` ¤

approve_builder `async` ¤

cancel_order `async` ¤

cancel_order_by_id `async` ¤

cancel_orders `async` ¤

cancel_orders_by_id `async` ¤

cancel_twap `async` ¤

create_sub_account `async` ¤

create_vault `async` ¤

delegate_tokens `async` ¤

modify_order `async` ¤

modify_orders `async` ¤

place_order `async` ¤

place_orders `async` ¤

place_twap `async` ¤

register_referrer `async` ¤

reserve_weight `async` ¤

schedule_cancellation `async` ¤

send_spot `async` ¤

send_usd `async` ¤

set_referrer `async` ¤

stake_tokens `async` ¤

transfer_account_funds `async` ¤

transfer_tokens `async` ¤

transfer_usd `async` ¤

transfer_vault_funds `async` ¤

unstake_tokens `async` ¤

update_leverage `async` ¤

update_margin `async` ¤

withdraw_funds `async` ¤