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

# Create TWAP Order

> This endpoint allows users to create a TWAP order that splits an amount into market orders over a set duration.

```http theme={null}
POST /api/v1/orders/twap/create
```

A TWAP order splits `amount` into smaller market orders, called sub-orders, and sends them over `duration_in_seconds`. Each sub-order uses `slippage_percent` as its maximum slippage.

This endpoint creates a TWAP order that the matching engine runs. It has no price limit and no randomized slices. For those settings, create a TWAP [order strategy](https://docs.pacifica.fi/api-documentation/api/rest-api/order-strategies/strategy-parameters.md#twap) instead.

#### How a TWAP order runs

* Pacifica plans one sub-order for every 30 seconds of `duration_in_seconds`, plus one. It plans fewer if `amount` holds fewer lots than that, so each sub-order is at least one lot.
* Pacifica sends one sub-order about every 30 seconds.
* Each sub-order is the remaining amount divided by the remaining sub-order count, rounded down to the lot size. It is at most 3 times the planned sub-order amount.
* The order ends as `completed` when the full amount fills.
* The order ends as `expired` if part of the amount is still unfilled after the last planned sub-order, or when its time runs out. Its `expiration` is 30 seconds after the end of `duration_in_seconds`.
* If the engine rejects a sub-order, the order stops and ends as `rejected_due_to_sub_order`.
* You can have up to 4 open TWAP orders per account in each market.

#### Operation Type (for Signing)

| Header Field | Type | Content |
| - | - | - |
| `"type"` | string | `"create_twap_order"` |

#### Request Body

<table><thead><tr><th width="188">Field</th><th width="98">Type</th><th width="95">Need</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>`"account"`</td><td>string</td><td>required</td><td>User's wallet address</td><td>`42trU9A5...`</td></tr><tr><td>`"signature"`</td><td>string</td><td>required</td><td>Cryptographic signature</td><td>`5j1Vy9Uq...`</td></tr><tr><td>`"timestamp"`</td><td>integer</td><td>required</td><td>Current timestamp in milliseconds</td><td>`1716200000000`</td></tr><tr><td>`"symbol"`</td><td>string</td><td>required</td><td>Trading pair symbol</td><td>`BTC`</td></tr><tr><td>`"amount"`</td><td>string</td><td>required</td><td>Total amount to execute, in token units</td><td>`0.121`</td></tr><tr><td>`"side"`</td><td>string</td><td>required</td><td>Order side (bid/ask)</td><td>`bid`</td></tr><tr><td>`"reduce_only"`</td><td>boolean</td><td>required</td><td>Whether each sub-order is reduce-only</td><td>`false`</td></tr><tr><td>`"slippage_percent"`</td><td>string</td><td>required</td><td>Maximum slippage for each sub-order, in percent. For example, "0.5" means 0.5%. At most 2 decimal places</td><td>`0.5`</td></tr><tr><td>`"duration_in_seconds"`</td><td>integer</td><td>required</td><td>Time to spread the sub-orders over, in seconds. Minimum 30</td><td>`3600`</td></tr><tr><td>`"client_order_id"`</td><td>Full UUID string</td><td>optional</td><td>Client-defined order ID. Must not match another open TWAP order of yours in the same market</td><td>`f47ac10b-58cc-4372-a567-0e02b2c3d479`</td></tr><tr><td>`"agent_wallet"`</td><td>string</td><td>optional</td><td>Agent wallet address</td><td>`69trU9A5...`</td></tr><tr><td>`"expiry_window"`</td><td>integer</td><td>optional</td><td>Signature expiry in milliseconds</td><td>`30000`</td></tr><tr><td>`"builder_code"`</td><td>string</td><td>optional</td><td>Builder program code (3-16 alphanumeric characters). Not supported on spot markets</td><td>`MYCODE`</td></tr></tbody></table>

```json theme={null}
{
  "account": "42trU9A5...",
  "signature": "5j1Vy9Uq...",
  "timestamp": 1716200000000,
  "symbol": "BTC",
  "amount": "0.121",
  "side": "bid",
  "reduce_only": false,
  "slippage_percent": "0.5",
  "duration_in_seconds": 3600,
  "client_order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "agent_wallet": "69trU9A5...",
  "expiry_window": 30000
}
```

For this request, Pacifica plans 121 sub-orders of 0.001 BTC, about 30 seconds apart, if the BTC lot size is 0.001 or smaller.

#### Response

* Status 200: TWAP order created successfully

```json theme={null}
  {
    "success": true,
    "data": {
      "order_id": 13753364
    },
    "error": null,
    "code": null
  }
```

`order_id` is the TWAP order ID. Use it to cancel the order or to get its history.

* Status 400: Invalid request body, for example an unknown `side` or a `slippage_percent` with more than 2 decimal places
* Status 422: The engine rejected the order

```json theme={null}
  {
    "success": false,
    "data": null,
    "error": "The requested duration of twap order 10s is too short. Should be at least 30s",
    "code": 0,
    "error_id": "unspecified"
  }
```

* Status 500: Internal server error

#### Code Example (Python)

```python theme={null}
import requests

payload = {
    "account": "42trU9A5...",
    "signature": "5j1Vy9Uq...",
    "timestamp": 1716200000000,
    "symbol": "BTC",
    "amount": "0.121",
    "side": "bid",
    "reduce_only": False,
    "slippage_percent": "0.5",
    "duration_in_seconds": 3600,
    "client_order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

response = requests.post(
    "/api/v1/orders/twap/create",
    json=payload,
    headers={"Content-Type": "application/json"}
)

data = response.json()
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.