> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/market-data/openinteresthistory.md). # openInterestHistory {% hint style="info" %} `openInterestHistory` is a Hydromancer addition — it is not available on the native Hyperliquid API, which only exposes the *current* open interest. {% endhint %} ### 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 `startTime`s 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](#convention). ### Request * **Endpoint**: `POST /info` **Per coin:** ```json { "type": "openInterestHistory", "coin": "BTC", "interval": "1h", "startTime": 1753833600000, "endTime": 1753920000000 } ``` **Per sector:** ```json { "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](#sectors)). Mutually exclusive with `coin` | | `interval` | string | Yes | Bucket interval (see [valid intervals](#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 | | `` | 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: ```json [ { "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: ```json [ { "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 {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} **`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. {% endhint %} ### Rate limits 5 points per request (see [rate limits](/readme/rest-api/rate-limits-and-user-limits.md)). ### Examples {% tabs %} {% tab title="Python" %} ```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']}") ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); const apiKey = process.env.HYDROMANCER_API_KEY; const baseUrl = process.env.HYDROMANCER_API_URL || 'https://api.hydromancer.xyz'; async function oiHistory(body) { const resp = await axios.post( `${baseUrl}/info`, { type: 'openInterestHistory', ...body }, { headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` } } ); return resp.data; } // Per coin — daily BTC open interest for (const c of await oiHistory({ coin: 'BTC', interval: '1d', startTime: 1753833600000 })) { console.log(`${c.t} oi=${c.oiClose} usd=${c.oiUsd}`); } // Per sector — daily total HIP-3 open interest, in USD for (const c of await oiHistory({ sector: 'hip3', interval: '1d', startTime: 1753833600000 })) { console.log(`${c.t} hip3_usd=${c.oiUsdClose}`); } ``` {% endtab %} {% endtabs %} ### Common errors | Error | Cause | | ------------------------------------ | -------------------------------------------------------------------------------------------------------- | | `unsupported interval: ` | Interval string not in the valid list above | | `Missing startTime field` | `startTime` not provided | | `range too wide for interval : …` | The range at that interval exceeds the 5000-bucket cap — use a coarser interval or a narrower time range | | `invalid sector: ` | `sector` is not a keyword or a valid dex name | | ` has no open interest` | `coin` is a spot or outcome market (no perp open interest) |