> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/historical-data/usertwapstatusesbytime.md).

# userTwapStatusesByTime

Returns TWAP status events for a user with `time` ≥ `startTime` (or after a `cursor`), ordered **oldest-first** by `time` then `tx_index`.

For pagination: pass `startTime` for the first page, then on each subsequent page pass the `cursor` `"{time}_{tx_index}"` built from the **last record** of the previous response. When `cursor` is supplied, `startTime` is ignored and the boundary record is excluded from the next page (no duplicates).

`dex` is optional. Omit to return statuses from every perp DEX. Set to `"main_dex"` for the native Hyperliquid dex, or to a HIP-3 dex name (e.g. `"xyz"`) to scope to that dex.

**note: TWAP status events are retained for \~24h on the server, so this endpoint can return at most one day of history.**

## POST Request

<table><thead><tr><th width="161.9998779296875">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"userTwapStatusesByTime"</code></td></tr><tr><td><code>user</code></td><td>string</td><td>Ethereum address (0x-prefixed, 42 characters)</td></tr><tr><td><code>startTime</code></td><td>integer</td><td>Earliest <code>time</code> to include (Unix ms, inclusive). Skipped when <code>cursor</code> is used. Either <code>startTime</code> or <code>cursor</code> must be supplied</td></tr><tr><td><code>endTime</code></td><td>integer</td><td>Latest <code>time</code> to include (Unix ms, inclusive). Default: now (optional)</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Composite of <code>time</code> and <code>tx_index</code> with <code>"_"</code> separator (e.g. <code>"1734571490123_12"</code>). Take from the <strong>last record</strong> of the previous response (optional)</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max results to return. Default 100, max 500 (optional)</td></tr><tr><td><code>dex</code></td><td>string</td><td>Scope to a single perp DEX. <code>"main_dex"</code> for the native Hyperliquid dex, or a HIP-3 dex name (e.g. <code>"xyz"</code>). Omit for all dexes (optional)</td></tr></tbody></table>

{% tabs %}
{% tab title="cURL" %}

```bash
# First page
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userTwapStatusesByTime",
    "user": "0x0000000000000000000000000000000000000000",
    "startTime": 0,
    "limit": 100
  }'

# Next page — cursor built from the last record of the previous response
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userTwapStatusesByTime",
    "user": "0x0000000000000000000000000000000000000000",
    "cursor": "1734571490123_12",
    "limit": 100
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

url = 'https://api.hydromancer.xyz/info'
headers = {
    'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
    'Content-Type': 'application/json',
}
user = '0x0000000000000000000000000000000000000000'
limit = 500

params = {'type': 'userTwapStatusesByTime', 'user': user, 'startTime': 0, 'limit': limit}
while True:
    page = requests.post(url, json=params, headers=headers).json()
    if not page:
        break
    for status in page:
        ...  # process status event
    if len(page) < limit:
        break
    last = page[-1]
    params = {
        'type': 'userTwapStatusesByTime',
        'user': user,
        'cursor': f"{last['time']}_{last['tx_index']}",
        'limit': limit,
    }
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

const url = 'https://api.hydromancer.xyz/info';
const headers = {
    'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
    'Content-Type': 'application/json',
};
const user = '0x0000000000000000000000000000000000000000';
const limit = 500;

let params = { type: 'userTwapStatusesByTime', user, startTime: 0, limit };
while (true) {
    const { data: page } = await axios.post(url, params, { headers });
    if (!page.length) break;
    for (const status of page) { /* process status event */ }
    if (page.length < limit) break;
    const last = page[page.length - 1];
    params = {
        type: 'userTwapStatusesByTime',
        user,
        cursor: `${last.time}_${last.tx_index}`,
        limit,
    };
}
```

{% endtab %}
{% endtabs %}

***

## Response Fields

JSON array of TWAP status records, ordered **oldest-first** by `time` then `tx_index`.

| Field            | Type    | Description                                                                                                                                                           |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time`           | int     | Block time when the status was emitted (Unix ms) — **first half of the next-page `cursor`**                                                                           |
| `block_number`   | int     | L1 block number containing the status update                                                                                                                          |
| `tx_index`       | int     | Transaction index within the block — **second half of the next-page `cursor`**                                                                                        |
| `twap_id`        | int     | TWAP order identifier (matches `twap_id` on `userTwapSliceFills` / `userTwapSummaries`)                                                                               |
| `user`           | string  | Ethereum address                                                                                                                                                      |
| `coin`           | string  | Asset symbol                                                                                                                                                          |
| `side`           | string  | `"B"` (buy) or `"A"` (sell)                                                                                                                                           |
| `sz`             | string  | Total intended TWAP size, in contracts                                                                                                                                |
| `executed_sz`    | string  | Cumulative executed size at the time of this status, in contracts                                                                                                     |
| `executed_ntl`   | string  | Cumulative executed notional at the time of this status (USDC)                                                                                                        |
| `minutes`        | int     | TWAP duration, in minutes                                                                                                                                             |
| `reduce_only`    | boolean | `true` if the TWAP order is reduce-only                                                                                                                               |
| `randomize`      | boolean | `true` if slice timing is randomized                                                                                                                                  |
| `twap_timestamp` | int     | TWAP order timestamp (Unix ms) as recorded by the protocol                                                                                                            |
| `status`         | string  | Lifecycle status string (`"activated"`, `"finished"`, `"terminated"`, `"stopped"`, `"waitingForTrigger"`) or — when `is_error` is `true` — the protocol error message |
| `is_error`       | boolean | `true` if `status` carries an error message rather than a normal lifecycle string                                                                                     |
| `stop_px`        | string  | Stop price attached to the TWAP, or `null` if none                                                                                                                    |
| `trigger_px`     | string  | Trigger price for a trigger TWAP (`"waitingForTrigger"`), or `null` if none                                                                                           |
| `trigger_above`  | boolean | For trigger TWAPs: `true` = activates when mark price rises above `trigger_px`, `false` = below. `null` if no trigger                                                 |