> For the complete documentation index, see [llms.txt](https://docs.blockscholes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockscholes.com/data-access/rest-api/blockscholes-exchange.md).

# The blockscholes Exchange

How the Block Scholes API's "blockscholes" exchange works: a multi-venue composite of crypto prices, quotes, open interest, volume and funding, plus Block Scholes index and theoretical prices.

Set `exchange` to `"blockscholes"` to get one series that represents the whole market rather than a single venue. Depending on what you request, that series is one of two things:

* **A venue composite.** Prices, quotes, open interest, volume, order-book size and funding rates are fetched from each constituent venue and combined bucket by bucket, using the rules on this page.
* **A Block Scholes derived price.** Index prices, theoretical (model) prices and forward rates are calculated by Block Scholes' own pricing pipeline. They are published under `blockscholes` but are not averaged from venue data at request time.

The index and mark price endpoints (4.10 and 4.11) always return the derived series and take no `exchange` field. On every endpoint that does take `exchange`, `"blockscholes"` selects the series shown here:

| You request                                                                            | On `blockscholes` you get | How it's built                                                                                 |
| -------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- |
| `bid`, `ask`, `trade` prices (`/api/v1/price/quote`, `/api/v1/price/trade`)            | Composite                 | Per-currency average across constituent venues, then an equal-weight average of the currencies |
| Open interest, volume, bid/ask size (`/api/v1/analytic/oi`, `/api/v1/analytic/volume`) | Composite                 | Contract-size-normalised sum across constituent venues                                         |
| Funding rate (`/api/v1/rate/funding`)                                                  | Composite                 | Average across constituent venues                                                              |
| `index` price                                                                          | Derived                   | Volume-weighted, median-filtered average of the constituent venues                             |
| `theoretical` price (model-driven future and option fair value)                        | Derived                   | Futures curve and implied-volatility surface                                                   |
| Forward rate (`/api/v1/rate/forward`)                                                  | Derived                   | Annualised rate implied by the Block Scholes forward for that expiry                           |

## Which venues are in the composite?

The constituents for a `base_asset` and `asset_type` are the venues listed for that pair in the Block Scholes index configuration, so the composite draws on the same venue universe as the Block Scholes index. Each constituent market (one venue's pair in one quote currency) counts once. The constituent list is not exposed through the API and can change over time.

Composites cover spot, perpetual, future and option asset types, including their `-equity`, `-fx` and `-commodity` variants. Futures and options are combined contract by contract: the same expiry (and, for options, the same strike and call/put) on each venue. Only contracts listed on at least one constituent venue are available; arbitrary strikes and expiries are not.

## How the composite is calculated

Each request is split into time buckets at the requested `frequency`. For every bucket:

### Prices and quotes: `bid`, `ask`, `trade`

1. **One value per venue.** Each venue contributes its last value in the bucket.
2. **Standing quotes carry, trades do not.** A venue with no new bid or ask in the bucket contributes its last standing quote for up to **2 hours**, and never past the contract's expiry. A trade is never carried: a venue that did not trade in the bucket is left out of the trade average.
3. **Average, convert, then average again.** Venues quoting in the same currency are averaged together. Each per-currency average is converted to the requested quote currency at that bucket's Block Scholes index rate, and the per-currency averages are then averaged with **equal weight**.

### Open interest, volume and order-book size

1. **Normalise to the base asset.** Each venue's figure is multiplied by its contract size. Inverse contracts are also divided by the Block Scholes index spot price for that bucket.
2. **Carry levels, never flows.** A venue that did not publish in a bucket contributes its last known level: open interest for up to **24 hours**, bid/ask size for up to **1 hour**. Volume is never carried. The response has no field marking a carried value.
3. **Sum across venues.** The total is reported in units of the base asset, or converted to the requested quote currency (`output_quote_asset` or `quote_asset`) at the bucket's Block Scholes index rate.

The composite `bid` size is the total size displayed at each venue's own best bid. It is not the size available at the composite bid price.

### Funding rate

Venues quoting in the same currency are averaged together, and the per-currency averages are then averaged with equal weight. Funding rates are not currency-converted. A venue with no funding row in the bucket is left out.

## Withdrawn quotes and one-sided markets

A bid or ask of `0` means the venue has withdrawn that side. It is real data, not a price:

* A withdrawn side is excluded from the average and from its divisor.
* **Both sides come from the same venues.** If at least one venue quotes both sides in a bucket, any venue quoting only one side is left out of both the bid and the ask average for that bucket. If no venue quotes both sides, each side is averaged over whichever venues quote it, so the bid and the ask can come from different venues.
* If every venue has withdrawn a side, the composite publishes `0` for that side instead of omitting the bucket. Treat a `0` bid or ask as "no quote", not as a crossed market.

## Built-in quality checks

Every composite bucket passes these checks before it is returned. Anything unusual is flagged in the response's errors instead of being silently adjusted:

* **Crossed or impossible quotes.** A bucket where the composite bid is above the ask, a premium is negative, or (for USD option quotes) a call is above spot or a put is above its strike is returned with an error identifying the affected timestamps.
* **Bucket-accurate conversion.** Every venue is converted at the Block Scholes index rate for its own bucket, including quotes carried forward, so a carried quote is never converted at a stale rate.
* **No carry past expiry.** A futures or options leg never carries into or beyond its expiry, so an expired contract cannot hold up the composite.
* **Same-venue sides.** Bid and ask are matched to the same venues whenever any venue quotes both, keeping the composite spread internally consistent.

## Composite vs. Block Scholes Index Price

The composite and the index draw on the same venues but answer different questions:

|                  | `blockscholes` composite                                            | Block Scholes Index Price                                    |
| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ |
| Inputs           | Each venue's quotes, trades, OI, volume or funding                  | Each venue's prices and traded volume                        |
| Weighting        | Equal weight per quote currency (prices); straight sum (OI, volume) | Volume-weighted, with price-conformance and freshness scores |
| Outlier handling | None: every live venue counts                                       | Median-anchored deviation filter; stale venues excluded      |
| Calculated       | At request time from stored venue data                              | Continuously, by the Block Scholes index service             |
| Use it for       | Market-wide liquidity, positioning and spread analysis              | A manipulation-resistant reference price                     |

The index also feeds the composite: it supplies the FX rate used to convert venues quoted in other currencies, and the spot price used to normalise inverse contracts.

## Index and theoretical prices

On `blockscholes`, the `index` and `theoretical` price types are calculated by Block Scholes rather than averaged from venues at request time. They reuse the same venue universe, and they build on each other:

1. **Spot index.** Venue prices are converted to the reporting currency, filtered for staleness and for deviation from the cross-venue median, then weighted by price conformance, traded volume and freshness. `index` is available for spot, perpetual and listed futures, not for options or constant tenors such as `30d`.
2. **Futures curve and forward rates.** Dated futures index prices are built from the constituent venues' futures markets. Block Scholes compares each expiry with the spot index to get the implied annualised carry, `ln(F / S) / T`, and interpolates between listed expiries. The `theoretical` price of a future, including constant-maturity tenors, is the spot index grown at that curve, and `/api/v1/rate/forward` returns the annualised carry for the requested expiry. It is the market-implied carry, not a venue funding rate or a deposit rate.
3. **Option theoretical prices.** Each venue's option quotes are fitted to an implied-volatility surface, and the venue surfaces are blended into one Block Scholes surface that favours deeper, better-fitting venues. Options are priced from that surface against the forward from step 2, so a `theoretical` option price can be returned for strikes and expiries no venue lists, where the service supports it.

### Which one should I request?

| Goal                                                     | Request on `blockscholes`            |
| -------------------------------------------------------- | ------------------------------------ |
| A reference spot, perpetual or futures price             | `index`                              |
| A model-driven fair value or mark for a future or option | `theoretical`                        |
| The implied carry or basis for an expiry                 | `/api/v1/rate/forward`               |
| The market-wide book, spread or traded price             | `bid`, `ask`, `trade` (composite)    |
| Total positioning or activity                            | open interest and volume (composite) |

Because `theoretical` and `index` are anchored to the spot index and `bid`/`ask`/`trade` are plain venue averages, the two can differ. A wide gap between a composite quote and the theoretical or index price usually means thin or dislocated venues, not an error.

## FAQ

**Is the `blockscholes` bid/ask a tradable price?**\
No. It is an average of each venue's best bid or ask, not an order you can fill. For execution, query individual venues.

**Why doesn't the composite trade price update every bucket?**\
Trades are never carried. If no constituent venue traded in a bucket, there is no composite trade price for it.

**Can I see which venues contributed to a bucket?**\
No. The constituent list and per-venue contributions are not exposed. To compare venues, request each one by name.

**Why does the composite open interest stay flat when a venue stops reporting?**\
Open interest is a level, so a venue's last value is carried for up to 24 hours. After that, the venue drops out of the sum.


---

# 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.blockscholes.com/data-access/rest-api/blockscholes-exchange.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.
