# 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 (e.g. `"activated"`, `"finished"`) 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                                      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/readme/rest-api/historical-data/usertwapstatusesbytime.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.