> ## Documentation Index
> Fetch the complete documentation index at: https://public-perps-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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](/providers/hyperliquid/trading), [Lighter](/providers/lighter/trading), and [Ondo](/providers/ondo/trading).
</Info>

## placeTwapOrder

```typescript theme={null}
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.

<Info>
  `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.
</Info>

## cancelTwapOrder

```typescript theme={null}
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.

<Info>
  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](/sdk/account/get-running-twaps) once assigned to get the id `cancelTwapOrder` actually expects.
</Info>

**API Reference:** [POST /createAction · /executeAction](/api-reference/actions)