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 provider from getProviders(). Each provider documents its own extras and duration bounds on its own trading page — see Hyperliquid, Lighter, and Ondo.

​

placeTwapOrder

import { OrderSide, isSubmittedOrAccepted } from '@lifi/perps-sdk';

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

for (const r of result.results) {
  if (isSubmittedOrAccepted(r)) {
    console.log(r.twapId);
  } else {
    console.error(r.status, r.errorCode, r.error);
  }
}

Parameter	Type	Required	Description
provider	string	Yes	Provider identifier
address	Address	Yes	User’s wallet address
market	MarketRef	Yes	Target market ({ marketId, categoryId })
side	OrderSide	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 each sub-order’s size by up to ±20%. Ondo throws a ValidationError when it is sent
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 Submitted or Accepted result carries twapId — the provider-native identifier for the placed TWAP parent. A venue refusal does not throw; it arrives as a Failed result with error and an optional errorCode, which has no twapId. See Execution reports and Error Handling.

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

import { getOrders, isTwapOrder } from '@lifi/perps-sdk';

const { orders } = await getOrders(perps.client, {
  provider: 'hyperliquid',
  address: userAddress,
});
const twap = orders.find(isTwapOrder);

if (twap) {
  await perps.cancelTwapOrder({
    provider: 'hyperliquid',
    address: userAddress,
    market: { marketId: 'BTC', categoryId: 'hyperliquid' },
    twapId: twap.orderId,
  });
}

Or, with an id you already hold from placeTwapOrder:

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 is String(client_order_index), the client order index the backend issued for the placement. It is not the parent’s order index, which Lighter assigns asynchronously. Once assigned, read the TWAP parent from getOrders (filter with isTwapOrder) and pass its orderId as twapId; that is the id cancelTwapOrder expects.

TWAP parents are Orders with type: OrderType.TWAP, plus durationSeconds and startedAt. Their child orders carry the parent’s id in parentOrderId.

API Reference: POST /createAction · /executeAction