userFillsByTime

Get trading fills for a single user within a time range. Includes twap fills.

Get trading fills for a single user within a time range. Includes twap fills.

All data fully available from 28-07-2025. We have performed a full backfill of all fills the HL native API offered, meaning that we have full historical data for most traders except for some very high volume addresses. TWAP fills are included from 02-08-2025.

POST Request

Field	Type	Description
type	string	Must be "userFillsByTime"
user	string	Ethereum address (0x-prefixed, 42 characters)
startTime	integer	Earliest fill time to include (Unix ms, inclusive). Skipped when cursor is used. Either startTime or cursor must be supplied
endTime	integer	Latest fill time to include (Unix ms, inclusive). Default: now (optional)
cursor	string	Composite of time and txIndex with "_" separator (e.g. "1234567890000_23"). Take from the last record of the previous response (optional)
builder	string	Filter to fills routed through this builder address (0x-prefixed, 42 characters). Omit (or send null) for no filtering. A malformed, empty or non-string value is a 400 rather than a silently unfiltered result (optional)
aggregateByTime	boolean	true or false, false by default (optional)
dex	string	i.e. "xyz" or "main_dex", or omit for no filtering (optional)
limit	integer	Max results to return, default 2000 (optional)

cURL

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userFillsByTime",
    "user": "0x0000000000000000000000000000000000000000",
    "startTime": 1234567890000,
    "endTime": 1234567900000,
    "cursor": "1234567890000_23"
  }'

Python

import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'userFillsByTime',
        'user': '0x0000000000000000000000000000000000000000',
        'startTime': 1234567890000,
        'endTime': 1234567900000,
        'cursor': '1234567890000_12'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Javascript

import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'userFillsByTime',
        user: '0x0000000000000000000000000000000000000000',
        startTime: 1234567890000,
        endTime: 1234567900000,
        cursor: '1234567890000_12'
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}

---

Response Fields

Field	Type	Description
coin	string	Asset symbol
px	string	Fill price
sz	string	Fill size
side	string	"A" (sell) or "B" (buy)
time	int	Fill timestamp (ms)
startPosition	string	Position size before the fill
dir	string	Direction (e.g. "Open Long", "Close Short", "Settlement")
closedPnl	string	Closed PnL from this fill
hash	string	Transaction hash
oid	int	Order ID
crossed	boolean	Whether the order crossed the spread
fee	string	Fee amount
tid	int	Trade ID
cloid	string?	Client order ID (optional)
builderFee	string?	Builder fee (optional)
deployerFee	string?	Deployer fee (optional, HIP-3 fills only)
priorityGas	string?	Priority gas fee in HYPE (optional)
feeToken	string	Fee token (e.g. "USDC")
twapId	int?	TWAP order ID (null if not a TWAP fill)
txIndex	int	Transaction index

Response

[
  {
    "coin": "hyna:LIT",
    "px": "3.38",
    "sz": "306.0635",
    "side": "A",
    "time": 1766411264116,
    "startPosition": "306.0635",
    "dir": "Settlement",
    "closedPnl": "0.00",
    "hash": "0xe9700f27f4c60944eae90431e255630202d5000d8fc928168d38ba7ab3c9e32f",
    "oid": 276429539434,
    "crossed": false,
    "fee": "0.00",
    "tid": 587851719766407,
    "feeToken": "USDE",
    "twapId": null,
    "txIndex": 1
  }
]