> 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 page covers what the generated Reference pages cannot.** Each of the three operations has its own page rendered from the contract. This page covers what they share: why they are public, what the figures mean, and three places where 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

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 why 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.

## 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**, because these are indexer-local projections, not an all-time ledger. `coverage_start_ms` on the volume response tells you how far back a total 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, and 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` so that nobody can pass it off as the one-sided total.
* **Venue figures are quote-only.** There is no venue-wide base-unit total, on purpose. Base units do not add across markets, so the contract does not publish a number with no coherent unit.

## 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. This page documents them as decimal strings, based on "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 the contract gives no retention window, buffer size, or checkpoint cadence. So the contract does not tell you how far back `coverage_start_ms` can reach.
* **`quote_error` values are not enumerated.** The prose describes three causes (no mark mirrored, stale mark, overflow) but does not specify the strings, so you cannot branch on them 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexus.xyz/api-reference/guides/statistics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.