userTwapStatusesByTime

Paginate a user's TWAP order status events by time, oldest-first.

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

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

cURL

# 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
  }'

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,
    }

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,
    };
}

---

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