PerpsClient Methods

Complete reference for all PerpsClient trading methods

Complete reference for all PerpsClient trading methods.

placeOrder

Place an order (USER_AGENT mode only — auto-signs and submits).

const result = await perps.placeOrder(params);

Field	Type	Required	Description
address	string	Yes	User’s wallet address
provider	string	Yes	Provider identifier
asset	AssetIdentity	Yes	Target asset ({ assetId, market })
side	'BUY' | 'SELL'	Yes	Order direction
type	'MARKET' | 'LIMIT' | 'TRIGGER_ONLY'	No	Order type
size	string	Yes	Order size
price	string	Yes	Limit price or slippage limit
leverage	number	No	Leverage to set
reduceOnly	boolean	No	Only reduce position
timeInForce	string	No	GTC, IOC, POST_ONLY, GTT
expiresAt	string	No	Unix ms timestamp expiry for GTT (must be in the future)
takeProfit	TriggerOrderInput	No	Take profit trigger
stopLoss	TriggerOrderInput	No	Stop loss trigger

Returns: ExecuteActionResponse with results[] array.

---

buildOrder

Build order payloads for signing (works in both USER and USER_AGENT mode). In USER_AGENT mode, automatically injects the agent address as signerAddress.

const { actions } = await perps.buildOrder(params);

// Sign each action with the user's wallet
const signedActions = await Promise.all(
  actions.map(async (a) => ({
    action: a.action,
    typedData: a.typedData,
    signature: await walletClient.signTypedData({ ...a.typedData }),
  }))
);

await perps.submitSignedOrder({
  provider: 'hyperliquid',
  address: userAddress,
  actions: signedActions,
});

Parameters: Same as placeOrder.

Returns: CreateActionResponse with actions[] array.

---

cancelOrders

Cancel one or more orders (USER_AGENT mode only).

const result = await perps.cancelOrders(params);

Field	Type	Required	Description
address	string	Yes	User’s wallet address
provider	string	Yes	Provider identifier
ids	string[]	Yes	Order IDs to cancel

---

buildCancelOrder

Build cancel order payloads for signing (works in both USER and USER_AGENT mode). In USER_AGENT mode, automatically injects the agent address as signerAddress.

const { actions } = await perps.buildCancelOrder({
  provider: 'hyperliquid',
  address: userAddress,
  ids: ['12345678'],
});

Returns: CreateActionResponse with actions[] array.

---

submitSignedOrder

Submit pre-signed order payloads (USER mode).

const result = await perps.submitSignedOrder(params);

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
actions	SignedActionStep[]	Yes	Signed actions from createAction

Each SignedActionStep:

Field	Type	Required	Description
action	string	Yes	Action type from the create response
typedData	object	Yes	Original typedData from createAction
signature	string	Yes	User’s or agent’s signature of the typedData

---

buildModifyOrder

Build modify order payloads for signing (works in both USER and USER_AGENT mode). In USER_AGENT mode, automatically injects the agent address as signerAddress.

const { actions } = await perps.buildModifyOrder({
  provider: 'hyperliquid',
  address: userAddress,
  modifications: [{ id: '12345678', price: '94500.00' }],
});

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
modifications	ModifyOrderInput[]	Yes	Modifications to apply

Returns: CreateActionResponse with actions[] array.

---

modifyOrders

Modify orders with automatic agent signing (USER_AGENT mode only).

const result = await perps.modifyOrders({
  provider: 'hyperliquid',
  address: userAddress,
  modifications: [{ id: '12345678', price: '94500.00' }],
});

Parameters: Same as buildModifyOrder.

Returns: ExecuteActionResponse with results[] array.

---

buildTriggerOrder

Build trigger-only order payloads (TP/SL on existing positions). Works in both USER and USER_AGENT mode.

const { actions } = await perps.buildTriggerOrder({
  provider: 'hyperliquid',
  address: userAddress,
  asset: { assetId: 'BTC', market: 'hyperliquid' },
  side: 'SELL',
  takeProfit: { triggerPrice: '100000.00' },
});

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
asset	AssetIdentity	Yes	Target asset ({ assetId, market })
side	'BUY' | 'SELL'	Yes	Order side
takeProfit	TriggerOrderInput	No	Take profit trigger
stopLoss	TriggerOrderInput	No	Stop loss trigger

Returns: CreateActionResponse with actions[] array.

---

placeTriggerOrder

Place trigger-only orders with automatic agent signing (USER_AGENT mode only).

const result = await perps.placeTriggerOrder({
  provider: 'hyperliquid',
  address: userAddress,
  asset: { assetId: 'BTC', market: 'hyperliquid' },
  side: 'SELL',
  takeProfit: { triggerPrice: '100000.00' },
  stopLoss: { triggerPrice: '90000.00' },
});

Parameters: Same as buildTriggerOrder.

Returns: ExecuteActionResponse with results[] array.

---

buildPositionMargin

Build position margin adjustment payloads for signing.

const { actions } = await perps.buildPositionMargin({
  provider: 'hyperliquid',
  address: userAddress,
  asset: { assetId: 'BTC', market: 'hyperliquid' },
  action: 'add',
  amount: '500.00',
});

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
asset	AssetIdentity	Yes	Target asset
action	'add' | 'remove'	Yes	Add or remove margin
amount	string	Yes	Margin amount

Returns: CreateActionResponse with actions[] array.

---

updatePositionMargin

Adjust position margin with automatic agent signing (USER_AGENT mode only).

Parameters: Same as buildPositionMargin.

Returns: ExecuteActionResponse with results[] array.

API Reference: POST /actions