openInterestHistory

Historical OHLC of open interest, per coin or per sector, in contracts and USD.

openInterestHistory is a Hydromancer addition — it is not available on the native Hyperliquid API, which only exposes the current open interest.

Overview

Returns open interest as an OHLC time series, rolled up to any interval, reconstructed minute-by-minute from fills and periodic on-chain state. Two modes:

• Per coin — pass coin. Returns OI in contracts (OHLC) plus its USD notional. oiClose matches Hyperliquid's openInterest for that coin 1:1.

• Per sector — pass sector. Returns the summed USD OI across a group of markets (OHLC). Contracts aren't additive across different markets, so sector OI is dollars only.

coin and sector are mutually exclusive. History is available from 2025-08-01; earlier startTimes are clamped to that.

Open interest follows the Hyperliquid convention — it is two-sided: the sum of all long and all short positions (equivalently, 2× the one-sided outstanding contracts). See Convention.

Request

• Endpoint: POST /info

Per coin:

{
    "type": "openInterestHistory",
    "coin": "BTC",
    "interval": "1h",
    "startTime": 1753833600000,
    "endTime": 1753920000000
}

Per sector:

{
    "type": "openInterestHistory",
    "sector": "hip3",
    "interval": "1d",
    "startTime": 1753833600000
}

Field	Type	Required	Description
coin	string	One of coin/sector	Coin name. For HIP-3 assets, prefix with dex name (e.g. "xyz:SP500")
sector	string	One of coin/sector	Market group to aggregate (see sectors). Mutually exclusive with coin
interval	string	Yes	Bucket interval (see valid intervals)
startTime	number	Yes	Start time in milliseconds since epoch (inclusive). Clamped to 2025-08-01
endTime	number	No	End time in milliseconds since epoch (exclusive). Defaults to now
limit	number	No	Maximum number of buckets to return. Default and max: 5000

Sectors

sector	Aggregates
total	Every market on every dex
native	The core Hyperliquid dex only
hip3	Every builder (HIP-3) dex — i.e. everything except native
<dexName>	A single named dex, e.g. "xyz", "hyna"

An unknown dex name returns an empty array.

Valid intervals

Interval	Duration
1m	1 minute
3m	3 minutes
5m	5 minutes
15m	15 minutes
30m	30 minutes
1h	1 hour
2h	2 hours
4h	4 hours
8h	8 hours
12h	12 hours
1d	1 day
3d	3 days
1w	1 week (Monday-aligned)
1M	1 month (calendar month)

Response

Returns a JSON array sorted by time ascending. Maximum 5000 buckets per request.

Per coin — OI in contracts (OHLC) plus USD:

[
    {
        "t": 1753833600000,
        "oiOpen": "34871.33654",
        "oiHigh": "34929.32676",
        "oiLow": "34672.06294",
        "oiClose": "34841.65018",
        "oiUsd": "2083983622.21634"
    }
]

Field	Type	Description
t	number	Bucket start time (milliseconds)
oiOpen	string	Open interest (contracts) at the bucket open
oiHigh	string	Highest open interest in the bucket
oiLow	string	Lowest open interest in the bucket
oiClose	string	Open interest at the bucket close. Matches Hyperliquid's openInterest 1:1
oiUsd	string | null	USD notional = oiClose × mark. null when no mark is known (see note)

Per sector — USD only:

[
    {
        "t": 1753833600000,
        "oiUsdOpen": "9569412034.55",
        "oiUsdHigh": "9612388120.10",
        "oiUsdLow": "9540117234.22",
        "oiUsdClose": "9585021998.71"
    }
]

Field	Type	Description
t	number	Bucket start time (milliseconds)
oiUsdOpen	string	Summed USD OI across the sector at the bucket open
oiUsdHigh	string	Highest summed USD OI in the bucket
oiUsdLow	string	Lowest summed USD OI in the bucket
oiUsdClose	string	Summed USD OI at the bucket close

Convention

Open interest is two-sided, following the Hyperliquid convention: it is the sum of all long and all short positions (equivalently, 2× the one-sided outstanding contracts). This matches Hyperliquid's openInterest and Hydromancer's oi field 1:1. The USD value uses the oracle mark price, falling back to the last-trade price where no oracle price exists.

oiUsd may be null. A bucket has no USD value when no mark price was known for that market at that time — e.g. a freshly-listed market before its first trade, or history before the oracle price feed began (2025-08-01). The open interest itself (contracts) is always present; only the USD denominator is unknown. Sector totals simply skip such markets.

Rate limits

5 points per request (see rate limits).

Examples

Python

import requests
import os

api_key = os.environ["HYDROMANCER_API_KEY"]
base_url = os.getenv("HYDROMANCER_API_URL", "https://api.hydromancer.xyz")

def oi_history(body):
    return requests.post(
        f"{base_url}/info",
        json={"type": "openInterestHistory", **body},
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"},
    ).json()

# Per coin — daily BTC open interest
for c in oi_history({"coin": "BTC", "interval": "1d", "startTime": 1753833600000}):
    print(f"{c['t']}  oi={c['oiClose']}  usd={c['oiUsd']}")

# Per sector — daily total HIP-3 open interest, in USD
for c in oi_history({"sector": "hip3", "interval": "1d", "startTime": 1753833600000}):
    print(f"{c['t']}  hip3_usd={c['oiUsdClose']}")

JavaScript

Common errors

Error	Cause
unsupported interval: <x>	Interval string not in the valid list above
Missing startTime field	startTime not provided
range too wide for interval <x>: …	The range at that interval exceeds the 5000-bucket cap — use a coarser interval or a narrower time range
invalid sector: <x>	sector is not a keyword or a valid dex name
<coin> has no open interest	coin is a spot or outcome market (no perp open interest)