> 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/guides/statistics.md).

# Venue Statistics

**This is the context the generated Reference pages cannot carry.** Each of the three operations has its own page rendered from the contract; what follows is what they share — why they are public, what the figures mean, and the three places a plausible reading is wrong.

Aggregate venue telemetry: cumulative traded volume, open interest, and the distribution of account balances. **Three operations, all public** — they declare `security: []`, so no API key is needed.

These are the venue-wide figures. Per-account state lives on the Account pages in the Reference sidebar and the Positions pages.

## Aggregate by construction — and that is a guarantee, not a limitation

Every schema on this page is documented as carrying **no per-account data at all**: *"Aggregate only — it carries no account id, address, or per-account volume by construction."* That is the contract's own wording, and it is the reason these endpoints are public while everything on Account is not.

If you are building a public dashboard, a market-data page, or an agent that needs venue context, **these are the endpoints to use.** Do not derive venue aggregates by fanning out over per-account reads.

## On this page

| Operation                                                                       | Path                              | What it returns                                        |
| ------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------ |
| [Cumulative volume](/api-reference/statistics/fetch-cumulative-volume.md)       | `GET /stats/volume`               | Cumulative traded notional, venue total and per market |
| [Open interest](/api-reference/statistics/fetch-open-interest.md)               | `GET /stats/open-interest`        | Open interest, long and short reported separately      |
| [Balance distribution](/api-reference/statistics/fetch-balance-distribution.md) | `GET /stats/balance-distribution` | Accounts per balance band                              |

**Two more `/stats` operations are documented elsewhere.** `GET /stats` (venue snapshot) and `GET /stats/history` (throughput samples) are tagged `Markets` in the contract and are covered on [`GET /stats`](/api-reference/markets/fetch-stats.md). All five are public.

None of the three operations here has an `/api/v1` twin — they are gateway paths only.

## Testnet data is illustrative, and the contract says so in-band

All three responses carry two fields you should surface rather than strip:

| Field     | Meaning                                                                                    |
| --------- | ------------------------------------------------------------------------------------------ |
| `testnet` | boolean, **always `true`** today. The data is illustrative.                                |
| `note`    | a human-readable disclaimer, including the one-sided-versus-gross warning on open interest |

Figures **restart when the service does** — these are indexer-local projections, not an all-time ledger. `coverage_start_ms` on the volume response is what tells you how far back a total actually reaches.

## Decimals are strings

Every notional figure is a lossless decimal serialized as a string (the [`Decimal`](/api-reference/guides/schemas.md#decimal) schema). **Parse with a decimal type, never a float.** `account_count` and `count` are JSON integers; timestamps are Unix epoch milliseconds ([`TimestampMs`](/api-reference/guides/schemas.md#timestampms)).

## The two sides are never pre-summed, and the naming is deliberate

Read this before captioning any number from this endpoint.

* **`long_oi_quote` (or `short_oi_quote`) is the figure to caption.** On a matched book the two are equal by construction; a persistent difference means the projection has desynced from the engine.
* **`gross_oi_two_sided_quote` is `long + short`** — twice the one-sided figure. It is named `gross` and `two_sided` precisely so it cannot be passed off as the one-sided total.
* **Venue figures are quote-only.** There is deliberately no venue-wide base-unit total: base units do not add across markets, so the contract refuses to publish a number with no coherent unit rather than publish one.

## Related

* [`GET /stats`](/api-reference/markets/fetch-stats.md) — `GET /stats` and `GET /stats/history`, plus per-market summaries and risk parameters.
* the Tickers pages in the Reference sidebar — 24-hour rolling price and volume statistics per market.
* [Schemas](/api-reference/guides/schemas.md) — component schema reference.

## Open questions

Gaps in the contract, flagged rather than filled:

* **No schemas are declared for the sub-objects' bounds types.** `BalanceBucket.min` and `max` carry descriptions but no declared type in the contract; they are documented here as decimal strings on the strength of "in USDX collateral" and the page-wide decimal convention.
* **`testnet` is typed as a boolean but documented as "always `true`".** There is no stated behaviour for a deployment where it would be `false`, and no operation exposes which deployment you are talking to.
* **Retention is unstated.** All three are described as restarting with the service, but no retention window, buffer size, or checkpoint cadence is given — so how far back `coverage_start_ms` can reach is not knowable from the contract.
* **`quote_error` values are not enumerated.** Three causes are described in prose (no mark mirrored, stale mark, overflow) but the strings themselves are not specified, so they cannot be branched on safely.


---

# 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/guides/statistics.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.