# WebSocket API **Connection URL:** `wss://prod-websocket-api.blockscholes.com/` ## 1. Subscription Feeds Overview The Block Scholes WebSocket API streams real-time pricing, implied volatility, and derived analytics over a single persistent connection. It is designed for clients that need continuous, low-latency updates and want to consume many datapoints from one socket rather than polling a REST endpoint. The interface follows the **JSON-RPC 2.0** standard. After authenticating, clients send a `subscribe` request describing one or more **batches** — groups of related datapoints to receive together — and the server pushes updates back over the same connection whenever the underlying values change. Subscriptions can optionally be **EIP-712 signed** for on-chain verification, making the same feeds usable as a pull-based oracle source. **At a glance** * One persistent WebSocket connection per client. * JSON-RPC 2.0 messaging — `authenticate`, `subscribe`. * Subscriptions are organised into batches, each with a configurable publishing rate, formatting options, and an optional `client_id` for in-place updates. * Updates carry only changed values; clients should be event-driven, not poll-driven. * Optional EIP-712 signatures on every update for trustless on-chain consumption. ### **1.1 Instrument Pricing** | **Feed Type** | **Feed Name** | **Description** | | -------------------------------------------- | --------------- | ---------------------------------------------------------- | | [Mark Price](#id-4.1-mark-price) | `mark.px` | Mark prices for specified instruments. | | [Index Price](#id-4.2-index-price) | `index.px` | Index prices for specified assets. | | [Settlement Price](#id-4.3-settlement-price) | `settlement.px` | Time-weighted spot index price (TWAP) at or before expiry. | ### **1.2 Implied Volatility Surface** | **Feed Type** | **Feed Name** | **Description** | | ---------------------------------------------------------- | -------------- | -------------------------------------------------- | | [IV by Strike](#id-4.3-implied-volatility-by-strike) | `strike.iv` | Implied volatility for given strike prices. | | [IV by Delta](#id-4.4-implied-volatility-by-delta) | `delta.iv` | Implied volatility for specified delta levels. | | [IV by Moneyness](#id-4.5-implied-volatility-by-moneyness) | `moneyness.iv` | Implied volatility for specified moneyness levels. | | [IV Index](#id-4.7-implied-volatility-index-bsiv) | `index.iv` | Block Scholes Implied Volatility Index (BSIV). | ### **1.3 Market Data** | **Feed Type** | **Feed Name** | **Description** | | ------------------------------------------------------- | --------------- | -------------------------------- | | [Calibrated Model Parameters](#id-4.7-model-parameters) | `model.params` | Calibrated SVI model parameters. | | [Interest Rates](#id-4.8-interest-rates) | `interest.rate` | Forward-implied interest rates. | ### **1.4 Realized Volatility** | **Feed Type** | **Feed Name** | **Description** | | --------------------------------------------------- | -------------- | ---------------------------------------------------- | | [Realized Volatility](#id-4.10-realized-volatility) | `realized.vol` | Annualized realized volatility for supported assets. | ## 2. Authentication Connections must be authenticated before any subscriptions can be made. The API follows the **JSON RPC 2.0** standard. [Reach out for a free API key](/other/contact.md#request-free-trial-api-key) ### 2.1 Using API Key **Description:** Authenticates the WebSocket connection using an API key. **Method:** `authenticate` **Request:** ```json { "jsonrpc": "2.0", "method": "authenticate", "params": { "api_key": "xxx" } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueThe method name. Must be "authenticate".
paramsObjecttrueParameters object containing authentication credentials.
params.api_keyStringtrueYour API key for authentication.
**Response (Success):** ```json { "jsonrpc": "2.0", "result": "ok" } ``` **Response Explanation:** | Field | Type | Description | | ----------- | ------ | ---------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | String | Authentication result. "ok" indicates success. | *** ## 3. Subscription Configuration ### 3.1 Batching A **batch** is a group of related subscriptions sent in a single `subscribe` call and delivered together in a single update message. Each entry in `batch[]` is its own subscription — its own feed, instrument, and parameters — but they share a publishing cadence (`frequency`), formatting options, and (optionally) a `client_id` that lets you address and mutate the whole group as one unit. Batching is the recommended way to consume multiple related datapoints. It cuts message overhead, keeps related values time-aligned in the same notification, and — via `client_id` — gives you a stable handle for swapping the batch's contents in place as your needs change (different strikes, new tenors, added or removed items) without tearing the subscription down and rebuilding it. **Batching Rules:** * Updates are sent **only if values change**. This means different batches may contain different subsets of datapoints of the total subscribed for. * Batch frequency defines **maximum publishing rate**. Actual publish rate differs based on underlying datatype calculation frequency. * Default limit: **10 items per batch** (adjustable). **Key Batch Parameters:**
ParameterTypeMandatoryDescription
frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms etc
client_idStringfalseOptional batch identifier. Re-subscribing with the same client_id overwrites the previous batch in place — this is the canonical way to mutate an existing batch's contents (swap strikes, change tenors, add or remove items) without an explicit unsubscribe. Omit client_id to register an independent batch that cannot be overwritten by later subscriptions and must be torn down explicitly. The subscribe acknowledgement echoes the entire subscription back to you, and client_id is carried on every subsequent update notification's envelope.
batchArraytrueArray of subscription entry parameters
batch[i].sidStringtrueClient-defined label for this batch item. Use it to attach your own context (currency, strike, tenor, internal row key, anything you need on the receiving side). The subscribe acknowledgement echoes the full subscription — so every sid comes back to you — and each subsequent update carries the matching sid under params.data.values[i].sid so you can map updates back to your own data structures
optionsObjecttrueFormatting and signature options. Please refer to Formatting Options.
**Identifying batches and items** The API exposes two identifier hooks that serve different purposes. The subscribe acknowledgement echoes your entire subscription back — including `client_id` and every `sid` — so you can confirm the server registered exactly what you sent. Both identifiers are then carried on every subsequent update for that subscription. `sid` is per item. Whatever you put on `batch[i].sid` comes back unchanged on every update for that entry under `params.data.values[i].sid`. The intent is to let you stash whatever context the receiving side needs — the instrument symbol, a row index, a tag like `"BTC-100000-C-26DEC26"`, a downstream destination key — so your handler can demultiplex incoming values without re-deriving them from the feed name and request parameters. `client_id` is per batch. Every update notification for that batch carries it on the parent envelope. Its load-bearing property is that re-subscribing with the same `client_id` **replaces the existing batch in place**: the previous contents are dropped and the new `batch` array becomes active, with no need to send `unsubscribe` first. This is how clients should update a live subscription. Subscriptions sent without a `client_id` are independent — they cannot be overwritten by later subscriptions and must be torn down explicitly via `unsubscribe`. In practice, a typical client keeps a stable `client_id` per logical subscription group and a meaningful `sid` per item; updates can then be dispatched purely from those two echoed identifiers, with no parsing of the feed payload required. *** ### 3.2 EIP-712 Signing Signing with [EIP-712 signatures](https://eips.ethereum.org/EIPS/eip-712) is supported for update messages as an optional feature, allowing integrity & provenance verification on-chain. To enable, include the signature configuration along with domain information in the subscription request. For type definitions and detailed verification schema, refer to the [**Pull Oracle**](/blockchain-oracle/pull-based-oracle.md) documentation section. **Example with EIP-712 Signature:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [ { "frequency": "1000ms", "batch": [ ... ], "options": { "format": { "timestamp": "ms", "hexify": true, "decimals": 9 }, "signature": { "domain": { "name": "TRIAL", "version": "1", "chain_id": "50000", "verifying_contract": "0x1111111111111111111111111111111111111111" } } } } ] } ``` *** ### 3.3 Formatting Options The `options.format` object allows customization of data formatting in subscription responses.
OptionTypeMandatoryDescription
timestampStringtrueTimestamp precision. Valid values: s (seconds), ms (milliseconds), ns (nanoseconds)
hexifyBooleantrueIf enabled, all numeric values will be transmitted as hex strings.
decimalsInteger or ObjecttrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled by 10decimals. When no signing is requested, numerical values will be rounded to the specified number of decimals. Integer applies to entire batch. Object allows per-sid precision (e.g., {"0x1": 9, "0x2": 5})
### 3.4 Retries and rate limits #### 3.4 Retries and rate limits Subscribe operations are rate-limited via a per-API-key token bucket: each item added by a `subscribe` request consumes tokens, and the bucket refills over time up to a maximum burst size. The bucket is **shared across every connection on your API key**, so opening additional connections does not give you a larger bucket, and multiple in-flight subscribes compete for the same pool of tokens. Burst size and refill rate vary per plan and are not exposed by the API — contact your Block Scholes representative if you need your specific limits. **When a `subscribe` is rejected with a rate-limit error**, retry only the specific subscribe that was rejected. Do not replay other batches you have in flight, and do not open new connections to re-send the same items — they all spend from the same bucket, so reissuing them just extends the throttle. **Recommended retry policy:** 1. On the first rate-limit rejection of a `subscribe`, wait a few seconds before retrying that same subscribe. 2. If it's rejected again, double the wait, with a small amount of random jitter to avoid synchronised retries from multiple clients sharing your key. 3. Cap the wait at a sensible upper bound (e.g. one minute) — waiting longer than a fully-refilled bucket buys you nothing. 4. Reset the wait once the subscribe succeeds. Larger batches need proportionally longer waits than smaller ones because every item consumes its own tokens. **Non-rate-limit errors are not retried with backoff.** Permission denials, invalid parameters, unsupported instruments and the like will not succeed on retry — they need the request fixed. Resend the corrected `subscribe` immediately. On a partial failure where the response surfaces per-`sid` errors, resend only the failed items, not the whole batch. **Sanity check for client implementations:** * Treat rate-limit errors and validation errors as two distinct paths. Backoff applies to the first, never the second. * The token bucket is per API key, not per connection — extra connections share the same bucket. * On reconnect, re-issue your subscriptions in the same batches; previously-registered subscriptions do not survive a dropped connection. Stagger reconnect-time resubscribes if you have many, rather than firing them all at once. * If you consistently hit the rate limit under normal operation, the answer is a plan adjustment so please reach out or fewer items per second — not more aggressive retry logic. *** ## 4. Subscription Feeds ### 4.1 Mark Price **Description:** Streams live mark prices for specified instruments. Futures and options support any `expiry` of choice, and options support any `strike` of choice as well, allowing user to price any instrument. **Feed Name:** `mark.px`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "1000ms", "client_id": "mark_subscription_1", "batch": [{ "sid": "0x1", "feed": "mark.px", "asset": "option", "base_asset": "BTC", "quote_asset": "USD", "model": "SVI", "strike": 100000, "type": "C", "expiry": "2025-12-26T08:00:00Z" }, { "sid": "0x2", "feed": "mark.px", "asset": "perpetual", "base_asset": "BTC", "quote_asset": "USDC" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be mark.px.
params.batch.assetStringtrueAsset type. Valid values: option, future, perpetual, spot.
params.batch.base_assetStringtrueThe currency to be added to the provided feed. Please check the table for the Supported base assets.
params.batch.quote_assetStringfalseQuote asset (e.g. USD, USDT, USDC). Default: USD.
params.batch.modelStringfalse

The mathematical model used to fit market quotes and interpolate or extrapolate values. Allowed values:

  • SVI
  • Spline

Default: SVI.

Required for "options".

params.batch.strikeInteger/FloatfalseStrike price. Required if asset is option.
params.batch.moneynessArrayfalseList of moneyness (strike / forward) values. Range: greater than 0, up to 4. Supply either strike or moneyness for options
params.batch.typeStringfalseOption type. Valid values: C (Call), P (Put). Required if asset is option.
params.batch.expiryISO 8601 stringfalseExpiry date/time. Required if asset is option or future.
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "client_id": "mark_subscription_1", "batch": [{ "sid": "0x1", "feed": "mark.px", "asset": "option", "base_asset": "BTC", "quote_asset": "USD", "model": "SVI", "strike": 100000, "type": "C", "expiry": "2025-12-26T08:00:00Z" }, { "sid": "0x2", "feed": "mark.px", "asset": "perpetual", "base_asset": "BTC", "quote_asset": "USDC" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "0x1", "v": 9561.1178 }, { "sid": "0x2", "v": 103928.0873 } ], "timestamp": 1762261424000 }, "client_id": "mark_subscription_1" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The mark price value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.2 Option Greeks **Description:** Streams option greeks — `delta`, `gamma`, `vega`, `theta`, `volga`, `vanna` — alongside the option's mark price. Greeks do not have a feed name of their own: they are an extension of the `mark.px` feed, requested by adding a `greeks` array to a `mark.px` batch item whose `asset` is `option`. Each requested greek is returned as its own field on the same value object as the mark price, on the same notification cadence. **Feed Name:** `mark.px` (with `greeks` field set)\ **Method:** `subscribe`\ **Applies to:** options only — greeks are rejected for `future`, `perpetual`, or `spot` assets. **Request:** {% code overflow="wrap" %} ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "client_id": "greeks_subscription_1", "batch": [{ "sid": "0x1", "feed": "mark.px", "asset": "option", "base_asset": "BTC", "quote_asset": "USD", "model": "SVI", "strike": 100000, "type": "C", "expiry": "2025-12-26T08:00:00Z", "greeks": ["delta", "gamma", "vega", "theta", "volga", "vanna"] }, { "sid": "0x2", "feed": "mark.px", "asset": "option", "base_asset": "BTC", "quote_asset": "USD", "model": "SVI", "moneyness": [0.95, 1.00, 1.05], "type": "C", "expiry": "2026-12-26T08:00:00Z", "greeks": ["delta"] } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } } ] } ``` {% endcode %} All fields match [4.1 Mark Price](#id-4.1-mark-price); the additional field is:
FieldTypeMandatoryDescription
params.batch.assetStringtrueValid values: option
params.batch.greeksArraytrueGreeks to compute and return alongside the mark price. Valid values: delta, gamma, vega, theta, volga, vanna
params.batch.greeksfalse
**Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "0x1", "v": 9561.1178, "delta": 0.5217, "gamma": 0.0001, "vega": 142.3401, "theta": -18.5621, "volga": 22.7104, "vanna": -3.0822 }, { "sid": "0x2", "moneyness": [0.95, 1.00, 1.05], "v": [9561, 9400, 9300], "delta": [0.6231, 0.5042, 0.3811] } ], "timestamp": 1762261424000 }, "client_id": "greeks_subscription_1" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | ---------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The mark price value. | | **params.data.values.delta** | Float | Returned if `delta` was requested. | | **params.data.values.gamma** | Float | Returned if `gamma` was requested. | | **params.data.values.vega** | Float | Returned if `vega` was requested. | | **params.data.values.theta** | Float | Returned if `theta` was requested. | | **params.data.values.volga** | Float | Returned if `volga` was requested. | | **params.data.values.vanna** | Float | Returned if `vanna` was requested. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | Greeks fields are only present in the update for the greeks that were listed in the `greeks` array on the request — fields you didn't request are **omitted, not null.** *** ### 4.3 Index Price **Description:** Streams real-time index prices for specified assets. **Feed Name:** `index.px`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "1000ms", "client_id": "index_subscription_1", "batch": [{ "sid": "idx_1", "feed": "index.px", "asset": "spot", "base_asset": "BTC", "quote_asset": "USD", "index_spread": true, }, { "sid": "idx_2", "feed": "index.px", "asset": "future", "base_asset": "ETH", "quote_asset": "USDT", "expiry": "2025-12-26T08:00:00Z" }, { "sid": "idx_3", "feed": "index.px", "asset": "perpetual", "exchange": "blockscholes", "base_asset": "BTC" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be index.px.
params.batch.assetStringtrueAsset type. Valid values: spot, future, perpetual.
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.quote_assetStringfalseQuote asset (e.g. USD, USDT, USDC). Default: USD.
params.batch.expiryISO 8601 stringfalseExpiry date/time. Required if asset is future.
params.batch.index_spreadboolfalseIf true, includes the index bid/ask spread in the response. Default: false.
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "client_id": "index_subscription_1", "batch": [{ "sid": "idx_1", "feed": "index.px", "asset": "spot", "base_asset": "BTC", "quote_asset": "USDC, "index_spread": true }, { "sid": "idx_2", "feed": "index.px", "asset": "future", "base_asset": "ETH", "quote_asset": "USDT", "expiry": "2025-12-26T08:00:00Z" }, { "sid": "idx_3", "feed": "index.px", "asset": "perpetual", "exchange": "blockscholes", "base_asset": "BTC" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "idx_1", "v": 103940.45269, "s": 0.000432 }, { "sid": "idx_2", "v": 3518.75082 }, { "sid": "idx_3", "v": 103899.29266 } ], "timestamp": 1762261149500 }, "client_id": "index_subscription_1" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The index price value. | | **params.data.values.s** | Float | Optional. The spread index value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.4 Settlement Price **Description:** Streams real-time time-weighted spot index price at or before the specified expiry. The time weighting of the price is performed on the 31m worth of data leading up to settlement. **Feed Name:** `settlement.px`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "1000ms", "client_id": "settlement_subscription_1", "batch": [{ "sid": "0x01", "feed": "settlement.px", "expiry": "2025-12-26T20:00:00Z", "base_asset": "AAVE" }, { "sid": "0x02", "feed": "settlement.px", "expiry": "2025-12-14T17:55:00Z", "base_asset": "SOL" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 9 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be settlement.px.
params.batch.expiryISO 8601 stringtrueSettlement expiry date/time.
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "client_id": "settlement_subscription_1", "batch": [{ "sid": "0x01", "feed": "settlement.px", "expiry": "2025-12-26T20:00:00Z", "base_asset": "AAVE" }, { "sid": "0x02", "feed": "settlement.px", "expiry": "2025-12-14T17:55:00Z", "base_asset": "SOL" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 9 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | -------------- | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **id** | Integer/String | The same identifier from the request. | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Object | Echo of the complete subscription configuration. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "0x01", "v": 115537.32174749 }, { "sid": "0x02", "v": 185.432156789, } ], "timestamp": 1762259941000 }, "client_id": "settlement_subscription_1" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The time-weighted average settlement price value. | | **params.data.values.is\_final** | Boolean | Indicates whether the settlement price is final. False if the request is made before or in the seconds immediately after the settlement datetime (expiry). | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.5 Implied Volatility by Strike **Description:** Streams real-time implied volatility values at specific strike levels. The `expiry` and `strike` fields can take arbitrary values, enabling users to pick any point on the underlying volatility surface. **Feed Name:** `strike.iv`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "1000ms", "client_id": "strike_iv_1", "batch": [{ "sid": "s1", "feed": "strike.iv", "exchange": "composite", "base_asset": "BTC", "strike": [100000], "expiry": "2025-12-26T08:00:00Z" }, { "sid": "s2", "feed": "strike.iv", "exchange": "composite", "base_asset": "BTC", "strike": [200000], "expiry": "2025-12-14T08:00:00Z" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be strike.iv.
params.batch.exchangeStringtrueExchange name (e.g., composite, deribit).
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.modelStringfalseModel type. Valid values: SVI, Spline. Default: SVI.
params.batch.strikeString, Integer/Float, List[Float]trueA list of strikes found on the given exchange (please refer to our catalog endpoint to obtain exchange-specific strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry.
params.batch.expiryISO 8601 stringtrueExpiry date/time.
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "client_id": "strike_iv_1", "batch": [{ "sid": "s1", "feed": "strike.iv", "exchange": "composite", "base_asset": "BTC", "strike": [100000], "expiry": "2025-12-26T08:00:00Z" }, { "sid": "s2", "feed": "strike.iv", "exchange": "composite", "base_asset": "BTC", "strike": [200000], "expiry": "2025-12-14T08:00:00Z" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "s1", "strike": [100000.0], "v": [0.46222] }, { "sid": "s2", "strike": [200000.0], "v": [0.64501] } ], "timestamp": 1762259615500 }, "client_id": "strike_iv_1" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The implied volatility value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.6 Implied Volatility by Delta **Description:** Streams real-time implied volatility values for specified delta levels. The `expiry` and `delta` fields can take arbitrary values, enabling users to pick any point on the underlying volatility surface. **Feed Name:** `delta.iv`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [ { "frequency": "20000ms", "client_id": "BS_DELTA_TEST", "batch": [ { "sid": "0x101", "feed": "delta.iv", "exchange": "composite", "base_asset": "BTC", "expiry": "2025-12-26T08:00:00Z", "delta": [0.5, 0.45, 0.1] }, { "sid": "0x102", "feed": "delta.iv", "exchange": "composite", "base_asset": "BTC", "expiry": "2025-12-14T08:00:00Z", "delta": [0.2, 0.3] } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be delta.iv.
params.batch.exchangeStringtrueExchange name (e.g., composite, deribit).
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.modelStringfalseModel type. Valid values: SVI, Spline. Default: SVI.
params.batch.deltaFloattrueDelta level. Valid values include: 0.5, 0.45, 0.40, 0.35, 0.30, 0.25, 0.20, 0.15, 0.10, 0.05, 0.04, 0.03, 0.02, 0.01 (both positive and negative).
params.batch.expiryISO 8601 stringtrueExpiry date/time.
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "20000ms", "client_id": "BS_DELTA_TEST", "batch": [{ "sid": "0x101", "feed": "delta.iv", "exchange": "composite", "base_asset": "BTC", "expiry": "2025-12-26T08:00:00Z", "delta": [0.5, 0.45, 0.1] }, { "sid": "0x102", "feed": "delta.iv", "exchange": "composite", "base_asset": "BTC", "expiry": "2025-12-14T08:00:00Z", "delta": [0.2, 0.3] } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "0x101", "delta": [0.1, 0.45, 0.5], "v": [0.46448, 0.43855, 0.44285] }, { "sid": "0x102", "delta": [0.2, 0.3], "v": [0.42911, 0.42306] } ], "timestamp": 1762258729500 }, "client_id": "BS_DELTA_TEST" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The implied volatility value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.7 Implied Volatility by Moneyness **Description:** Streams real-time implied volatility values at given moneyness ratios (strike/forward). The `expiry` and `moneyness` fields can take arbitrary values, enabling users to pick any point on the underlying volatility surface. **Feed Name:** `moneyness.iv`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "20000ms", "client_id": "BS_MONEYNESS_TEST", "batch": [{ "sid": "0x101", "feed": "moneyness.iv", "exchange": "composite", "base_asset": "ETH", "expiry": "2025-12-14T08:00:00Z", "moneyness": [0.5, 2, 1] }, { "sid": "0x102", "feed": "moneyness.iv", "exchange": "composite", "base_asset": "BTC", "expiry": "30d", "moneyness": [0.5, 2, 1] } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be moneyness.iv.
params.batch.exchangeStringtrueExchange name (e.g., composite, deribit).
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.modelStringfalseModel type. Valid values: SVI, Spline. Default: SVI.
params.batch.moneynessFloattrueMoneyness level. Valid values range from 0.1 to 3.0.
params.batch.expiryISO 8601 stringtrueExpiry date/time.
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "20000ms", "client_id": "BS_MONEYNESS_TEST", "batch": [{ "sid": "0x101", "feed": "moneyness.iv", "exchange": "composite", "base_asset": "ETH", "expiry": "2025-12-14T08:00:00Z", "moneyness": [0.5, 2, 1] }, { "sid": "0x102", "feed": "moneyness.iv", "exchange": "composite", "base_asset": "BTC", "expiry": "30d", "moneyness": [0.5, 2, 1] } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "0x101", "moneyness": [1.0, 2.0, 0.5], "v": [0.68182, 0.87968, 1.03505] }, { "sid": "0x102", "moneyness": [1.0, 2.0, 0.5], "v": [0.43735, 0.75756, 0.82217] } ], "timestamp": 1762258013000 }, "client_id": "BS_MONEYNESS_TEST" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The implied volatility value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.8 Implied Volatility Index (BSIV) **Description:** Streams real-time Block Scholes Implied Volatility Index (BSIV) for constant tenors. **Feed Name:** `index.iv`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [ { "frequency": "1000ms", "client_id": "BS_INDEX_IV_TEST", "batch": [ { "sid": "90d", "feed": "index.iv", "exchange": "composite", "base_asset": "ETH", "expiry": "90d" }, { "sid": "30d", "feed": "index.iv", "exchange": "composite", "base_asset": "ETH", "expiry": "30d" }, { "sid": "7d", "feed": "index.iv", "exchange": "composite", "base_asset": "ETH", "expiry": "7d" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be index.iv.
params.batch.exchangeStringtrueExchange name (e.g., composite).
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.expiryStringtrueConstant tenor (e.g. 7, 14, 30, 90, 180, 365)
params.optionsObjecttrueFormatting and signature options. See Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "client_id": "BS_INDEX_IV_TEST", "batch": [{ "sid": "90d", "feed": "index.iv", "exchange": "composite", "base_asset": "ETH", "model": "SVI", "expiry": "90d" }, { "sid": "30d", "feed": "index.iv", "exchange": "composite", "base_asset": "ETH", "model": "SVI", "expiry": "30d" }, { "sid": "7d", "feed": "index.iv", "exchange": "composite", "base_asset": "ETH", "model": "SVI", "expiry": "7d" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "v": 72.37018, "sid": "90d" }, { "v": 74.15651, "sid": "30d" }, { "v": 76.38079, "sid": "7d" } ], "timestamp": 1762257552500 }, "client_id": "BS_INDEX_IV_TEST" } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The IV index value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ### 4.9 Model Parameters **Description:** Streams real-time calibrated model parameters for the given exchange and expiry. **Feed Name:** `model.params`\ **Method:** `subscribe` **Important Notes:** * Model Parameters cannot be mixed with other data types in the same batch. **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "20000ms", "client_id": "model_params_1", "batch": [{ "sid": "mp_1", "feed": "model.params", "exchange": "composite", "asset": "option", "base_asset": "BTC", "model": "SVI", "expiry": "2025-12-26T08:00:00Z" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.client_idStringfalseOptional identifier for this subscription.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be model.params.
params.batch.exchangeStringtrueExchange name. Eg., "composite"
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.assetStringtrueSupports "option" asset
params.batch.modelStringfalseModel type. Default: SVI.
params.batch.expiryISO 8601 stringtrueExpiry date/time.
params.optionsObjecttrueFormatting and signature options. Please refer Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "20000ms", "client_id": "model_params_1", "batch": [{ "sid": "mp_1", "feed": "model.params", "exchange": "composite", "asset": "option", "base_asset": "BTC", "model": "SVI", "expiry": "2025-12-26T08:00:00Z" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "mp_1", "alpha": 0.0099, "beta": 0.0864, "rho": -0.0054, "m": 0.0939, "sigma": 0.1935 } ], "timestamp": 1762251931000 }, "client_id": "model_params_1" } ] } ``` **Data Update Explanation:**
FieldTypeDescription
jsonrpcStringJSON-RPC protocol version. Always "2.0".
methodStringAlways "subscription" for data updates.
paramsArrayArray containing update data objects.
params.dataObjectData object containing values and timestamp.
params.data.valuesArrayArray of value objects, one per sid.
params.data.values.sidStringSubscription identifier matching the request.
params.data.values.alphaFloatControls the overall level of total variance.
params.data.values.betaFloatControls the skewness of the variance smile.
params.data.values.rhoFloatControls the rotation of the smile.
params.data.values.mFloatControls the horizontal translation of the smile.
params.data.values.sigmaFloatControls atm curvature of the smile.
params.data.timestampIntegerTimestamp when the data was recorded.
*** ### 4.10 Interest Rates **Description:** Streams real-time forward-implied interest rates for supported assets. Supports any `expiry` of choice, allowing user to pick any point on the forward curve. **Feed Name:** `interest.rate`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "1000ms", "batch": [{ "sid": "ir_1", "feed": "interest.rate", "base_asset": "BTC", "expiry": "2025-10-31T08:00:00Z" }, { "sid": "ir_2", "feed": "interest.rate", "base_asset": "ETH", "expiry": "2025-12-26T08:00:00Z" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 7 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be interest.rate.
params.batch.base_assetStringtrueThe base asset (ie. BTC)
params.batch.expiryISO 8601 stringtrueExpiry date/time.
params.optionsObjecttrueFormatting and signature options. Please refer Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "batch": [{ "sid": "ir_1", "feed": "interest.rate", "base_asset": "BTC", "expiry": "2025-10-31T08:00:00Z" }, { "sid": "ir_2", "feed": "interest.rate", "base_asset": "ETH", "expiry": "2025-12-26T08:00:00Z" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 7 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "ir_1", "v": 0.0223746 }, { "sid": "ir_2", "v": 0.0227152 } ], "timestamp": 1762250026000 } } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The interest rate value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | ### 4.11 Realized Volatility **Description:** Streams real-time annualized realized volatility for supported assets and time windows. **Feed Name:** `realized.vol`\ **Method:** `subscribe` **Request:** ```json { "jsonrpc": "2.0", "method": "subscribe", "params": [{ "frequency": "1000ms", "batch": [{ "sid": "rv_1", "feed": "realized.vol", "asset": "spot-fx", "base_asset": "EUR", "lookback": "7d" }, { "sid": "rv_2", "feed": "realized.vol", "asset": "spot-fx", "base_asset": "EUR", "lookback": "30d" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 7 } } } ] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
jsonrpcStringtrueJSON-RPC protocol version. Must be "2.0".
methodStringtrueMust be "subscribe".
paramsArraytrueArray containing subscription configuration objects.
params.frequencyStringtrueMax publishing rate. Eg., values: 1000ms, 20000ms.
params.batchArraytrueArray of subscription parameter objects.
params.batch.sidStringtrueUnique identifier for this subscription item.
params.batch.feedStringtrueFeed type. Must be realized.vol.
params.batch.base_assetStringtrueThe base asset (ie. EUR)
params.batch.assetStringtrueAsset type. Valid values: spot-fx.
params.batch.lookbackStringtrueTime window of the retrieve realized vol. e.g. 7d
params.optionsObjecttrueFormatting and signature options. Please refer Formatting Options.
**Response (Subscription Confirmation):** ```json { "jsonrpc": "2.0", "result": [{ "batch": { "frequency": "1000ms", "batch": [{ "sid": "rv_1", "feed": "realized.vol", "asset": "spot-fx", "base_asset": "EUR", "lookback": "7d" }, { "sid": "rv_2", "feed": "realized.vol", "asset": "spot-fx", "base_asset": "EUR", "lookback": "30d" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 7 } } } } ] } ``` **Response Explanation:** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **result** | Array | Array containing subscription confirmation objects. | | **result.batch** | Array | Echo of the subscribed batch items. | **Data Update Example:** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [{ "data": { "values": [{ "sid": "rv_1", "v": 0.4291345 }, { "sid": "rv_2", "v": 0.5769210 } ], "timestamp": 1762252826000 } } ] } ``` **Data Update Explanation:** | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------- | | **jsonrpc** | String | JSON-RPC protocol version. Always "2.0". | | **method** | String | Always "subscription" for data updates. | | **params** | Array | Array containing update data objects. | | **params.data** | Object | Data object containing values and timestamp. | | **params.data.values** | Array | Array of value objects, one per sid. | | **params.data.values.sid** | String | Subscription identifier matching the request. | | **params.data.values.v** | Float | The realized vol value. | | **params.data.timestamp** | Integer | Timestamp when the data was recorded. | *** ## 5. Error Handling **Error Messages** WebSocket API errors follow the standard JSON-RPC 2.0 error format.
Error TypeError CodeExample ResponseDescription
Invalid API Key-2610
{
  "jsonrpc": "2.0",
  "error": {
    "message": "Invalid API Key",
    "code": -2610
  }
}
Occurs when an invalid or missing API key is provided. Ensure that a valid api_key is included in the authentication request.
Invalid method-2610
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -2610,
    "message": "Invalid method"
  }
}
Triggered when an invalid method name is specified in the request.
Invalid Params-2610
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -2610,
    "message": "Invalid parameters: xxxx"
  }
}
Occurs when required parameters are missing or invalid in the request.
Invalid Request-32600
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  }
}
The JSON sent is not a valid Request object.
*** ## 6. Usage Example Below is a complete example demonstrating authentication, subscription, receiving updates, and unsubscribing. **Step 1: Authenticate** ```json { "jsonrpc": "2.0", "id": 1, "method": "authenticate", "params": { "api_key": "your_api_key_here" } } ``` **Step 2: Subscribe to Mark Price** ```json { "jsonrpc": "2.0", "id": 2, "method": "subscribe", "params": [ { "frequency": "1000ms", "client_id": "my_subscription", "batch": [ { "sid": "btc_mark", "feed": "mark.px", "asset": "perpetual", "base_asset": "BTC", "quote_asset": "USD" } ], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 2 } } } ] } ``` **Step 3: Receive Updates** ```json { "jsonrpc": "2.0", "method": "subscription", "params": [ { "data": { "values": [ { "sid": "btc_mark", "v": 111370.50 } ], "timestamp": 1761811200000 } } ] } ``` **Step 4: Unsubscribe** ```json { "jsonrpc": "2.0", "id": 3, "method": "unsubscribe", "params": { "client_id": "my_subscription" } } ``` *** ## **7. Supported Base Assets**
feed_typebase_assets
mark.px / index.px

To fetch all the allowed currencies for pricing feeds, please use the catalog API with the following request body to call the Catalog API

{
    "fields": [],
    "start": "2025-10-06T06:00:00Z", //Use current date
    "end": "2025-10-06T06:00:00Z",  //Use current date
    "exchanges":["blockscholes"],
    "asset_types":["option"], // "spot"|"perpetual"|"future"
    "base_assets":[]
}
*.iv / model.params

To fetch all the allowed currencies for IV feeds, please use the catalog API with the following request body to call the Catalog API

{
    "fields": [],
    "start": "2025-10-06T06:00:00Z", //Use current date
    "end": "2025-10-06T06:00:00Z",  //Use current date
    "exchanges":["composite"],
    "asset_types":["option"],
    "base_assets":[]
}
interest.rate

To fetch all the allowed currencies for interest rates, please use the catalog API with the following request body to call the Catalog API

{
    "fields": [],
    "start": "2025-10-06T06:00:00Z", //Use current date
    "end": "2025-10-06T06:00:00Z",  //Use current date
    "exchanges":["blockscholes"],
    "asset_types":["future"],
    "base_assets":[]
}
*** --- # Agent Instructions: 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: ``` GET https://docs.blockscholes.com/data-access/websocket-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.