Objects and enums

Exact serialized values for Perps providers, actions, statuses, transactions, orders, margin modes, events and activity.

This page is the single reference for Perps enums and shared objects. Endpoint pages link here. Values are shown exactly as the API serializes them.

Providers

providerId	Description
hyperliquid	Hyperliquid main perpetual dex
hyperliquid-xyz	The HIP-3 builder-deployed “xyz” market set on Hyperliquid

Both settle in USDC on the hyperliquid network. Use GET /v1/providers for the live list and for each provider’s supportedActions. GET /v1/providers lists every provider; a project explicitly disabled for a provider or for Perps gets 403 EXECUTE_FORBIDDEN on POST /v1/actions.

Action types

action in Execute an action and type filter in List actions. All 14 values are accepted by the API.

Group	Values
Positions	open, close
Risk	updateLeverage, updateMargin
Orders	stopLoss, takeProfit, setTpAndSl, editOrder, cancelOrder
Account	fund, withdraw, approveAgent, approveBuilderFee, setUnifiedAccount

Action arguments

All fields of args are optional in the request schema; the action validates the ones it needs. R means required, O optional, blank means not used.

Action	Arguments
open	marketId R, side R, leverage R (integer 1 to 50, within the market’s leverageRange), one of amount or size R (not both), marginMode O, limitPrice O, stopLossPrice O, takeProfitPrice O
close	marketId R, size O (USD notional, minimum 10; omit to close the full position)
updateLeverage	marketId R, leverage R, marginMode O
updateMargin	marketId R, amount R (positive adds margin, negative removes; isolated positions only)
stopLoss	marketId R, stopLossPrice R, orderId O (update an existing one)
takeProfit	marketId R, takeProfitPrice R, orderId O
setTpAndSl	marketId R, stopLossPrice R, takeProfitPrice R, stopLossOrderId O, takeProfitOrderId O
editOrder	marketId R, orderId R, at least one of limitPrice or size (USD notional)
cancelOrder	marketId R, at least one of orderId or orderIds
fund	amount R (in the source token), fromToken R (network, optional address), fundingMethod O, skipApproval O
withdraw	amount R (USD)
approveAgent	agentAddress R, agentName R, validUntil O
approveBuilderFee	none
setUnifiedAccount	enabled R (boolean)

Notes on open:

• amount is margin in USD; size is position notional in USD. The notional must be at least 10 USD: size of at least 10, or amount times leverage of at least 10.
• With limitPrice the order is a limit order; without it, a market order.
• marginMode is cross or isolated and defaults to isolated. It cannot change while a position is open.
• close with size also requires at least 10 USD notional.

fundingMethod is bridge2 (direct Hyperliquid Bridge2, Arbitrum USDC only, minimum 5 USDC) or lifi (any supported token and network). When omitted, bridge2 is used for Arbitrum USDC and lifi otherwise.

Amounts and sizes are decimal strings; prices, leverage and validUntil are numbers.

Action statuses

status on an action: CREATED, WAITING_FOR_NEXT, PROCESSING, SUCCESS, FAILED, CANCELED, STALE.

An action starts as CREATED. Poll Get an action until it reaches SUCCESS, FAILED or CANCELED.

Transaction types

Each entry in transactions[] has a type, a status, a signingFormat and a signablePayload. signingFormat is EIP712_TYPED_DATA for Hyperliquid venue actions and EVM_TRANSACTION for Arbitrum funding transactions. The enum also declares SOLANA_TRANSACTION and COSMOS_TRANSACTION, which Perps providers do not use.

Declared type values: APPROVAL, OPEN_POSITION, CLOSE_POSITION, UPDATE_LEVERAGE, STOP_LOSS, TAKE_PROFIT, CANCEL_ORDER, EDIT_ORDER, FUND, WITHDRAW, APPROVE_BUILDER_FEE, ENABLE_DEX_ABSTRACTION, APPROVE_AGENT, UPDATE_MARGIN, SET_TP_AND_SL, SET_USER_ABSTRACTION.

Two types can be returned before the operation you requested, and must be signed and submitted in the order returned:

type	Returned when
APPROVE_BUILDER_FEE	Returned before open, close, stopLoss, takeProfit and setTpAndSl when the wallet’s approved maximum builder fee is below the builder fee applied to your orders. Also the type returned by the approveBuilderFee action. One-time per fee level.
SET_USER_ABSTRACTION	On an open, when your project has unified accounts enabled and the wallet is eligible (not already unified, with no open positions or resting orders). It is also the type returned for the setUnifiedAccount action.

ENABLE_DEX_ABSTRACTION is declared but not returned by current actions.

Transaction statuses

CREATED, QUEUED, BROADCASTED, CONFIRMED, FAILED, NOT_FOUND.

After Submit a transaction, a signedPayload for Hyperliquid or Arbitrum typed data moves to QUEUED; a transactionHash moves to BROADCASTED. Only a CREATED transaction can be submitted.

Order types and sides

Field	Values
Order type	market, limit, stop_loss, take_profit
Order side (Get orders), position side and open side	long, short
Event order side	buy, sell
Event order timeInForce	ioc, gtc, alo

Margin modes

marginMode: cross (collateral shared across positions) or isolated (dedicated collateral per position). A market lists the modes it allows in supportedMarginModes.

Position fields

Returned by Get positions.

Field	Meaning
marketId	Market of the position
side	long or short
size	Size in the base asset, as a string
entryPrice, markPrice	Entry and current mark price
leverage, marginMode	Current leverage and margin mode
margin	Margin allocated to the position
unrealizedPnl	Price PnL, excluding funding
funding	Net cumulative funding since open; positive is received, negative is paid
liquidationPrice	Price at which the position is liquidated
pendingActions	Actions available now (type, label, pre-filled args); pass one to POST /v1/actions

Event types

eventType: order_filled, liquidation, stop_loss_triggered, take_profit_triggered.

Each event has id, eventType, providerId, occurredAt, optional marketId, perpActionId (null for liquidations), providerOrderId, explorerUrl, and an order object with orderId, side, type, originalSizeBase, remainingSizeBase, and optional limitPrice, triggerPrice, fillPrice and closedPnl. Fill events are one per partial fill.

Activity

Get activity returns items with a type discriminator: event (an event object, ordered by occurredAt) or action (an action object, ordered by createdAt).