TWAP Orders

Place and cancel time-weighted average price orders via PerpsClient.placeTwapOrder and cancelTwapOrder

Place a TWAP (time-weighted average price) parent order that executes over a fixed duration, or cancel a running one, through PerpsClient.placeTwapOrder / PerpsClient.cancelTwapOrder. The registered provider plugin authorizes both flows with its SDK-managed credential; the user’s wallet is not prompted.

The examples on this page use Hyperliquid (provider: 'hyperliquid'). Replace the provider value with any supported DEX from getProviders(). Each provider documents its own extras and duration bounds on its own trading page — see Hyperliquid, Lighter, and Ondo.

placeTwapOrder

const result = await perps.placeTwapOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: 'BUY',
  size: '1.5',
  durationSeconds: 1800, // 30 minutes
});

console.log(result.results[0].twapId);

Parameter	Type	Required	Description
provider	string	Yes	Provider identifier
address	Address	Yes	User’s wallet address
market	MarketRef	Yes	Target market ({ marketId, categoryId })
side	'BUY' | 'SELL'	Yes	Order direction
size	string	Yes	Total base-asset size executed across the TWAP’s lifetime
durationSeconds	number	Yes	Total execution window in seconds
reduceOnly	boolean	No	Only reduce the position
randomize	boolean	No	Hyperliquid extra — randomize sub-order timing within the execution window
frequencySeconds	number	No	Ondo extra — interval between child orders in seconds
minPrice	string	No	Ondo extra — lowest acceptable child-order price
maxPrice	string	No	Ondo extra — highest acceptable child-order price

Returns: ExecuteActionResponse with results[] array. A successful result carries twapId — the provider-native identifier for the placed TWAP parent.

market, side, size, durationSeconds, and reduceOnly are the provider-independent core. The remaining fields are extras: a provider only honours the ones it advertises on its placeTwapOrder action’s params descriptors (GET /providers), and ignores extras it does not declare. See each provider’s trading page for which extras it supports and its own duration bounds.

cancelTwapOrder

const result = await perps.cancelTwapOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  twapId: '4521',
});

Parameter	Type	Required	Description
provider	string	Yes	Provider identifier
address	Address	Yes	User’s wallet address
market	MarketRef	Yes	Target market — required by every provider’s cancel wire even where the TWAP id is globally unique
twapId	string	Yes	Provider-native TWAP identifier: Hyperliquid’s numeric id, Ondo’s twap_-prefixed id, or Lighter’s order index (scoped per market)

Returns: ExecuteActionResponse with results[] array.

On Lighter, a placement result’s twapId carries the submit-time transaction hash — Lighter assigns the parent’s real order index asynchronously. Read the account’s running TWAPs once assigned to get the id cancelTwapOrder actually expects.

API Reference: POST /createAction · /executeAction