> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/statistics/fetch-open-interest.md).

# GET /stats/open-interest

Open interest, long and short reported separately.

`operationId`: `fetchOpenInterest`

**Authentication:** none — this operation is public.

Open interest per market and as a venue total, with the **long and short sides reported separately** rather than pre-summed.

**Read this first: which number to publish.** On a perpetual venue every long position is matched by an equal short, so `long_oi == short_oi` holds by construction and their sum is exactly TWICE the one-sided figure reference venues such as Hyperliquid and dYdX headline. Caption `long_oi_quote` (or `short_oi_quote`, which equals it). `gross_oi_two_sided_quote` is the sum, named so it cannot be mistaken for the one-sided figure — **it is NOT the quantity the BFF's `total_open_interest` on `GET /market-stats` carries** — that figure sums `/admin/risk-summary`'s per-market totals, which are raw position sizes in BASE units with the mark never multiplied in. To reconcile per market, compare the BFF's `open_interest` against `long_oi_base + short_oi_base`. There is deliberately no venue-level counterpart, because base units do not add across markets.

**Base versus quote.** `*_base` is the size open in the market's BASE asset (BTC for `BTC-USDX-PERP`). Base units do NOT add across markets — 3 BTC and 50 ETH sum to nothing — so the venue-level figures are quote-only and `*_base` appears per market only. `*_quote` is that size priced into quote notional (USDX) at `mark_price`.

**Where the mark price comes from, and when a quote figure is absent.** `mark_price_source` names it on every response. The mark is this indexer's mirror of the engine's `GET /markets/{market_id}/mark-price`, refreshed roughly every second and **withheld once it is older than 15 seconds** rather than served frozen. A market whose mark is absent, stale, or whose notional overflows keeps its `*_base` figures and carries `quote_error` instead of `*_quote`; absence is never zero. If a market that CARRIES open interest could not be priced, the venue `*_quote` fields are omitted too and the top-level `quote_error` names the markets — a partial venue total is never presented as complete. The venue figures are also withheld when the venue fold itself overflows `Decimal`, and that message names no market because every row priced; read `quote_error` rather than inferring the cause. A market with NOTHING open is exempt from all of that: no mark can change a zero, so it prices to `"0"` while still carrying the `quote_error` that says why it has no mark, and it never withholds the venue figure. Withholding the headline number because an EMPTY market lost its mark would lose it for the one reason that provably cannot affect it.

**Freshness, and the one thing no error field can tell you.** This is an in-memory projection folded from the engine's position stream and repaired from the engine's authoritative snapshot on a background sweep. Shortly after the service is rebuilt the mirror can be partially hydrated, and the figure reads low; the fold cannot distinguish that from a genuinely quiet venue, so no error field reports it. The sharpest form is a venue figure of `"0"` in the first seconds after a restart, when listed markets already exist and no mark has landed yet: that is the correct answer for what the mirror holds and the wrong one for what the venue holds, and this response cannot tell you which you are reading. Do not alert on a drop to zero without checking `as_of_ms` and the per-market `quote_error` values. `as_of_ms` — the last event this indexer ingested, on its OWN clock — is what tells a fresh snapshot from a stalled fold. It is not the last time open interest changed.

Values are decimal STRINGS, not JSON numbers, so they are exact; parse with a decimal type, never a float. Every listed market gets an entry, carrying `"0"` on both sides when nothing is open, so "no open interest" is distinguishable from "market unknown"; a delisted market appears only while it still carries a position. `testnet` is always `true` and `note` restates the one-sided warning in prose.

## Responses

| Status | Body                                                            | Meaning                                   |
| ------ | --------------------------------------------------------------- | ----------------------------------------- |
| `200`  | [`OpenInterest`](/api-reference/guides/schemas.md#openinterest) | Open interest, venue total and per market |

## Example

```bash
curl -X GET 'https://exchange.nexus.xyz/api/exchange/stats/open-interest'
```

***

<sub>Generated from</sub> <sub></sub><sub>`eng/apps/exchange/api/openapi.json`</sub> <sub></sub><sub>(spec</sub> <sub></sub><sub>`0.9.27`</sub><sub>). Do not edit by hand — regenerate with</sub> <sub></sub><sub>`python3 product/docs/tools/api-reference/generate.py`</sub><sub>. Hand-authored context lives in the Guides pages.</sub>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/statistics/fetch-open-interest.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.