perpPriceHistoryByTime
Returns the accepted oracle and mark prices of a perp within a time range
Rows are in ascending order (oldest first), one per oracle round (roughly every 3 seconds per dex). These are the prices the exchange actually uses for margining and liquidation, on every dex including HIP-3. For HIP-3 they are the values the network accepted for the round, not what the dex deployer submitted in its setOracle action — use oraclePriceHistoryByTime for the raw submission. For the native Hyperliquid dex both endpoints return the same validator round.
type
string
Must be "perpPriceHistoryByTime"
coin
string
symbol e.g. "BTC" or with dex prefix "xyz:XYZ100"
coins
string[]
batch form: 1–20 symbols. Returns an object keyed by coin instead of a flat array. Use either coin or coins.
startTime
int
ms unix timestamp
endTime
int
ms unix timestamp (optional)
limit
int
max 2000 (default 2000)
dex
string
DEX identifier e.g. "hyna", "xyz"; "main_dex" for the native dex (optional, returns all if omitted)
Request
curl -X POST https://api.hydromancer.xyz/info \
-H "Authorization: Bearer $HYDROMANCER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "perpPriceHistoryByTime",
"coin": "xyz:AAOI",
"startTime": 1787528956000,
"endTime": 1787528966000
}'import requests
import os
import json
response = requests.post(
'https://api.hydromancer.xyz/info',
json={
'type': 'perpPriceHistoryByTime',
'coin': 'xyz:AAOI',
'startTime': 1787528956000,
'endTime': 1787528966000
},
headers={
'Authorization': f'Bearer {os.environ["HYDROMANCER_API_KEY"]}',
'Content-Type': 'application/json'
}
)
print(json.dumps(response.json(), indent=2))Batch (multiple coins)
Pass coins (an array of 1–20 symbols) instead of coin to fetch several markets over the same time range in one request. startTime, endTime and dex apply to every coin. limit is per coin, max 100 in the batch form (default 100) — so a 20-coin batch returns at most ~2000 rows; use the single-coin form for a wider window on one market. The response is an object keyed by coin, each value the same row array as the single-coin form; a requested coin with no data maps to an empty array.
This is served by a single ClickHouse query (coin is the table's leading sort key), so it is cheaper than looping the single-coin request. Billing is 1 token per coin (a single-coin request is 1 token), and the rate-limit cost scales with the number of coins.
Response Fields
time
int
Block timestamp of the oracle round (ms)
blockNumber
int
Height of the block that committed the round — joins to userFillsByTime / block-level data
dex
string
DEX identifier ("hyperliquid" for the native dex)
coin
string
Trading pair
oraclePx
string?
Accepted oracle price. Omitted when the round carried no oracle slot for the asset: delisted native assets kept a frozen markPx with no oracle until 2026-06-13 (they drop out entirely after that), and the natively-priced HYPE/PURR miss the slot in ~2 rounds a day
markPx
string
Accepted mark price — the value used for margining, liquidations and funding. Always present
extPerpPx
string?
External perp reference price; omitted for assets without one
updateClass
string?
HIP-3 only: how the network sourced the round as reported by the node ("Deployer", "Fallback", "Normal"). Omitted for the native dex
When a block commits more than one oracle round for the same dex, the last round is returned.
Accepted HIP-3 rounds are available from 2026-02-24; native rounds from 2025-08-01.
Last updated