# REST API **Request URL:** `https://prod-data.blockscholes.com/` ## 1. Endpoints Overview Below is an overview of all available REST API endpoints. ### **1.1 Catalog Instruments** | **Category** | **Endpoint** | **Description** | | ------------------- | ---------------------------------------------- | ----------------------------------------------------- | | Catalog Instruments | [/api/v1/catalog](#id-4.1-catalog-instruments) | Catalog of instruments listed on specified exchanges. | ### **1.2 Implied Volatility Surface** | **Category** | **Endpoint** | **Description** | | ----------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | IV by Strike | [/api/v1/iv/strike](#id-4.3-implied-volatility-by-strike) | Implied volatility for given strike prices. | | IV by Delta | [/api/v1/iv/delta](#id-4.4-implied-volatility-by-delta) | Implied volatility for specified delta levels. | | IV by Moneyness | [/api/v1/iv/moneyness](#id-4.5-implied-volatility-by-moneyness) | Implied volatility for specified moneyness levels. | | IV by Risk Reversal (Call-Put Skew) | [/api/v1/iv/risk-reversal](#id-4.6-implied-volatility-by-risk-reversal-call-put-skew) | Risk reversal data derived from the implied volatility surface. | | IV by Butterfly Spread | [/api/v1/iv/butterfly-spread](#id-4.7-implied-volatility-by-butterfly-spread) | Butterfly spread data derived from the implied volatility surface. | | IV Index (BSIV) | [/api/v1/iv/index](#id-4.8-implied-volatility-index-bsiv) | The Block Scholes Implied Volatility Index (BSIV) for constant tenors. | | Calibrated Model Parameters | [/api/v1/modelparams](#id-4.9-model-parameters) | Calibrated SVI model parameters for a given exchange and expiry. | ### **1.3 Instrument Pricing** | **Category** | **Endpoint** | **Description** | | ---------------- | ------------------------------------------------------ | --------------------------------------------------- | | Index Price | [/api/v1/price/index](#id-4.10-index-prices) | Index price for a specified asset type. | | Mark Price | [/api/v1/price/mark](#id-4.11-mark-price) | Mark price for a specified asset type. | | Settlement Price | [/api/v1/price/settlement](#id-4.13-settlement-prices) | Time-weighted spot index price at or before expiry. | ### 1.4 **Market Data** | **Data Type** | **Endpoint** | **Description** | | --------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- | | Forward-Implied Rates | [/api/v1/rate/forward](#id-4.14-forward-implied-rates) | Forward-implied rates for supported assets. | | Funding Rates | [/api/v1/rate/funding](#id-4.15-funding-rates) | Perpetual funding rates. | | Mid Price | [/api/v1/price/mid](#id-4.12-mid-prices) | Mid-price for a given instrument. | | Treasury Rates | /api/v1/rate/treasury | Treasury yield curve daily (bank discount) rates for supported maturities. | | Quote Prices (BBO) | [/api/v1/price/quote](#id-4.19-quote-price) | Best bid & ask for respective instrument | | Trade Price | [/api/v1/price/trade](#id-4.17-trade-price) | Last traded price for respective instrument | | Open Interest | [/api/v1/analytic/oi](#id-4.18-open-interest-oi) | Returns aggregated open interest across supported exchanges. | | Trade Volume | [/api/v1/analytic/volume](#id-4.16-volume) | Returns aggregated trading volume data across supported exchanges. | ## 2. Authentication Requests must be authenticated and include the headers below. [Reach out for a free API key](https://docs.blockscholes.com/other/contact#request-free-trial-api-key) | Header | Value | Description | | ------------ | ---------------- | -------------------------- | | Content-Type | application/json | Format of the request body | | X-API-Key | {API\_KEY} | API Key for authentication | ## 3. Request Options A number of options are supported for applying & adjusting transformations on update messages. **Request Example:** ```json { "currency": "BTC", "expiry": "2023-10-05T00:00:00.000Z", "options": { "format": { "timestamp": "ms", "hexify": true, "decimals": 9 }, "signature": { "domain": { "name": "TRIAL", "version": "1", "chain_id": "50000", "verifying_contract": "0x1111111111111111111111111111111111111111" } } } } ``` ### 3.1 Object Definition
FieldTypeMandatoryDescription
formatObjecttrueSpecifies data formatting preferences for the response.
format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
format.decimalsIntegertrueNumber 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. Eg.: "decimals":9
signatureObjectfalseContains information about the signature domain specified by the client.
### 3.1 EIP-712 Signatures Message signing using the EIP-712 signatures are supported as an optional feature \ for most data requests, allowing integrity & provenance verification on-chain. To enable, include the signature tag along with domain information on each API \ Request For type definitions and detailed verification schema, refer to the [**Pull Oracle**](https://docs.blockscholes.com/blockchain-oracle/pull-based-oracle#verification-via-eip-712) documentation section. ## 4. Endpoints ### 4.1 Catalog Instruments **Description:** Returns the catalog of instruments listed on specified exchange(s). **Endpoint:** `/api/v1/catalog`\ **Method:** `POST` **Request Body:** ```json { "start": "2024-01-02T09:00:00Z", "end": "2024-01-02T09:00:00Z", "exchanges": ["blockscholes"], "asset_types": ["option"], "base_assets": ["BTC"], "quote_assets": [], "fields": [] } ``` **Request Explanation:**
FieldTypeMandatoryDescription
startISO 8601 stringtrueAn instrument is considered valid if it expires after the specified "start" date.
endISO 8601 stringtrueAn instrument is considered valid if it is listed before the specified "end" date.
exchangesList[str]trueList of exchanges for filtering Catalog instruments. Eg. "blockscholes".
asset_typesList[str]trueList of asset types for filtering Catalog instruments. Valid types are 'option', 'future', 'spot', 'perpetual'.
base_assetsList[str]falseList of base assets for filtering Catalog instruments. Please check the table for the Supported base assets.
quote_assetsList[str]falseOptional list of quote assets for filtering Catalog instruments.
fieldsList[str]falseOptional list of instrument’s fields to be returned in the response. Valid values correspond to the field names available in the Response Data section (e.g., exchange, asset_type, expiry, strike, etc.). Please refer the fields in the Response data. Eg. "fields": ["exchange", "asset_type", "expiry"]. If not specified, all fields will be returned by default.
**Response Data** ```json { "data": [ { "asset_type": "option", "exchange": "composite", "available_since": "2023-12-28T08:00:09.000Z", "listing": "2023-12-28T08:00:09.000Z", "base_asset": "BTC", "quote_asset": "BTC", "settlement_asset": "BTC", "expiry": "2024-12-27T08:00:00.000Z", "strike": 10000, "type": "C", "style": "european" }, … ] ``` **Response Explanation:**
FieldTypeDescription
dataListList of Catalog Instruments that match the filters in the request.
asset_typeStringRepresents the asset type of the instrument.
exchangeStringRepresents the exchange associated with the instrument.
available_sinceISO 8601 stringThe date and time when the instrument was made available.
listingISO 8601 stringThe date and time when the instrument was listed.
base_assetStringThe base asset of the instrument.
quote_assetStringThe quote asset of the instrument.
settlement_assetStringThe settlement asset of the instrument.
expiryISO 8601 stringThe date and time when the instrument expires. Only available for future and option asset types.
strikeIntegerAn integer indicating the strike price of the option. Only available for option asset type.
typeStringRepresents the type of the option. 'C' for call options and 'P' for put options. Only available for option asset type.
styleStringRepresents the style of the option. In the provided example, it's a European option. Only available for option asset type.
*** ### 4.2 Add Feed **Description:** Adds support for a new price feed on any token with active markets. Clients can expect to see requests (and websocket API subscriptions) for newly added tokens to start returning prices within 5 minutes from when the endpoint is called. This automation serves to streamline addition of new feeds on `index.px` and `mark.px` without having to go through a manual client support workflow. **Endpoint:** `/api/v1/feed/add`\ **Method:** `POST` **Request Body:** ```json { "feed": { "name": "index.px" }, "base_asset": "BTC", "asset_type": "spot" } ``` **Request Explanation:**
FieldTypeMandatoryDescription
feedObjecttrueDefines the feed metadata.
feed.nameStringtrueThe name of the feed Eg. mark.px, index.px.
base_assetStringtrueThe currency to be added to the provided feed. Please check the table for the Supported base assets.
asset_typeStringtrue

Type of asset this feed corresponds to (e.g., perpetual, spot ).

Allowed combinations:
• spot : index.px
• perpetual : mark.px

**Response Data** ```json { "status": "success", "message": "Successfully added feed for BTC (perpetual)" } ``` *** ### 4.3 Implied Volatility by Strike **Description:** Provides implied volatility values at specific strike levels. **Endpoint:** `/api/v1/iv/strike`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "BTC", "expiry": "2025-10-31T08:00:00Z", "model": "SVI", "start": "LATEST", "end": "LATEST", "strike": [100000.0, 200000.0], "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 0 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange (e.g., "blockscholes").
base_assetStringtrueThe currency for which implied volatility is being requested. Please check the table for the Supported base assets.
expiryStringtrueThe expiration date (in ISO 8601 format or constant tenor e.g., "7d").
modelStringfalse

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

  • SVI
  • Spline

Default: SVI

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
strikeList[float] or "listed"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. Note: In the case of strike endpoint "listed" should not be used when querying for arbitrary (non-market-listed) expiries, it is only valid for expiries that exist in the catalog. Eg. "strike":[3000, 3200] or "strike": "listed" . Non-listed / non-standard strikes are also supported when requested explicitly: "strike":[3281, 4257]
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "values": [ { "strike": 200000.0, "v": 1.67449 }, { "strike": 100000.0, "v": 0.86181 } ], "timestamp": 1761807600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the implied volatility data and associated metadata.
data.valuesListEach object inside the values list has the following fields: (strike, v)
data.values.strikeFloatThis represents the strike price.
data.values.vFloatThis represents the implied volatility value for the given strike price.
data.timestampFloatAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.4 Implied Volatility by Delta **Description:** Provides implied volatility values for specified delta levels. **Endpoint:** `/api/v1/iv/delta`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "ETH", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "delta": [0.1, 0.50], "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 2 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange (e.g., "composite").
base_assetStringtrueThe currency for which implied volatility is being requested. Please check the table for the Supported base assets.
expiryStringtrueThe expiration date (in ISO 8601 format or constant tenor e.g., "7d").
modelStringfalse

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

  • SVI
  • Spline

Default: SVI

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
deltaList[float] or "listed"trueA list of delta levels. Valid values include any of ["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 negative & positive, or "listed" to include all deltas calculated by default as standard pillars. Eg. "delta":[0.5, 0.45] or "delta": "listed" . Non-listed / non-standard deltas are also supported when requested explicitly: "delta":[0.43, 0.31]
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg., "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "values": [ { "delta": 0.5, "v": 0.66 }, { "delta": 0.1, "v": 0.72 } ], "timestamp": 1761807600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the implied volatility data and associated metadata.
data.valuesListEach object inside the values list has the following fields: (delta, v)
data.values.deltaFloatThis represents the delta level of the IV.
data.values.vFloatThis represents the implied volatility value.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.5 Implied Volatility by Moneyness **Description:** Provides implied volatility values at given moneyness ratios (strike/forward). **Endpoint:** `/api/v1/iv/moneyness`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "ETH", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "moneyness": [1.0, 2.0], "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 0 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange (e.g., "composite").
base_assetStringtrueThe currency for which implied volatility is being requested. Please check the table for the Supported base assets.
expiryStringtrueThe expiration date (in ISO 8601 format or constant tenor e.g., "7d").
modelStringfalse

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

  • SVI
  • Spline

Default: SVI

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
moneynessList[float] or "listed"trueA list of moneyness levels. Valid values range from 0.1 to 3, in increments of 0.1, or "listed" to include all moneyness currently listed on the exchange for the given expiry. Eg. "moneyness":[0.1, 0.2] or "moneyness": "listed" . We can also provide non-listed / non-standard moneyness. Eg. moneyness":[0.12, 0.22]
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "values": [ { "money": 1.0, "v": 0.6661 }, { "money": 2.0, "v": 2.16117 } ], "timestamp": 1761807600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the implied volatility data and associated metadata.
data.valuesListEach object inside the values list has the following fields: (moneyness, v)
data.values.moneynessFloatThis represents the moneyness level of the IV.
data.values.vFloatThis represents the implied volatility value.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.6 Implied Volatility by Risk Reversal (Call-Put Skew) **Description:** Provides risk reversal values representing the skew between calls and puts. **Endpoint:** `/api/v1/iv/risk-reversal`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "ETH", "model": "SVI", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "delta": [ 0.1, 0.2, 0.25 ], "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange (e.g., "composite").
base_assetStringtrueThe currency for which implied volatility is being requested. Please check the table for the Supported base assets.
expiryStringtrueThe expiration date (in ISO 8601 format or constant tenor e.g., "7d").
modelStringfalse

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

  • SVI
  • Spline

Default: SVI

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
deltaList[float] or "listed"trueValid values include any of [0.45, 0.4, 0.35, 0.3, 0.25, 0.2, 0.15, 0.1, 0.05, 0.04, 0.03, 0.02, 0.01] positive only, or "listed" to include all deltas calculated by default as standard pillars.. Eg. "delta":[0.4, 0.45] or "delta": "listed" . Non-listed / non-standard deltas are also supported when requested explicitly: "delta":[0.43, 0.31]
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. Numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "values": [ { "delta": 0.1, "v": -0.1112160081 }, { "delta": 0.2, "v": -0.0957562627 }, { "delta": 0.25, "v": -0.0823526868 } ], "timestamp": 1761807600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the implied volatility data and associated metadata.
data.valuesList

Each object inside the values list has the following

fields: (delta, v)

data.values.deltaFloatThis represents the delta level of the IV.
data.values.vFloatThis represents the implied volatility value.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.7 Implied Volatility by Butterfly Spread **Description:** Returns butterfly spread values at specific delta levels. **Endpoint:** `/api/v1/iv/butterfly-spread`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "ETH", "model": "SVI", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "delta": [0.1, 0.2, 0.25], "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange (e.g., "composite").
base_assetStringtrueThe currency for which implied volatility is being requested. Please check the table for the Supported base assets.
expiryStringtrueThe expiration date (in ISO 8601 format or constant tenor e.g., "7d").
modelStringfalse

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

  • SVI
  • Spline

Default: SVI

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
deltaList[float] or "listed"trueA list of delta levels. Valid values include any of [0.45, 0.4, 0.35, 0.3, 0.25, 0.2, 0.15, 0.1, 0.05, 0.04, 0.03, 0.02, 0.01] positive only, or "listed" to include all deltas calculated by default as standard pillars. Eg. "delta":[0.05, 0.45] or "delta": "listed" . Non-listed / non-standard deltas are also supported when requested explicitly: "delta":[0.43, 0.31]
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. Numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "values": [ { "delta": 0.1, "v": 0.1055129515 }, { "delta": 0.2, "v": 0.0439171329 }, { "delta": 0.25, "v": 0.0274426774 } ], "timestamp": 1761807600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the implied volatility data and associated metadata.
data.valuesList

Each object inside the values list has the following

fields: (delta, v)

data.values.deltaFloatThis represents the delta level of the IV.
data.values.vFloatThis represents the implied volatility value.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.8 Implied Volatility Index (BSIV) **Description:** Returns a composite implied volatility index for a given asset and tenor. **Endpoint:** `/api/v1/iv/index`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "BTC", "asset_type": "option", "expiry": "30d", "start": "LATEST", "end": "LATEST", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange (e.g., "composite").
base_assetStringtrueThe currency for which implied volatility is being requested. Please check the table for the Supported base assets.
expiryStringtrueThe expiration in constant tenor (e.g. 7, 14, 30, 90, 180, 365)
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. Numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "v": 47.8669535559, "timestamp": 1761807600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the implied volatility index data and associated metadata.
data.vFloatThis represents the implied volatility index vol value.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.9 Model Parameters **Description:** Provides calibrated model parameters for the given expiry and exchange. **Endpoint:** `/api/v1/modelparams`\ **Method:** `POST` **Request Body:** ```json { "exchange": "composite", "base_asset": "BTC", "model": "SVI", "expiry": "2025-12-26T08:00:00Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange i.e "composite".
base_assetStringtrueThe currency for which model params are being requested. Please check the table for the Supported base assets.
modelStringfalse

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

Default value is "SVI".

expiryISO 8601 stringtrueThe expiration date (ISO 8601 format).
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "alpha": 0.0077, "beta": 0.1053, "rho": -0.0911, "m": 0.0563, "sigma": 0.1838, "jw_atm_total_var": 0.0285, "jw_min_imp_var": 0.1727, "jw_atm_var": 0.1823, "jw_slope_right": 0.5674, "jw_slope_left": 0.6812, "jw_atm_skew": -0.1199, "timestamp": 1761811200000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the model parameter data and associated metadata.
data.alphaFloatControls the overall level of total variance.
data.betaFloatControls the skewness of the variance smile.
data.rhoFloatControls the rotation of the smile.
data.mFloatControls the horizontal translation of the smile.
data.sigmaFloatControls atm curvature of the smile.
data.jw_atm_total_varFloatThe total variance of the at-the-money options.
data.jw_min_imp_varFloatThe minimum implied variance across all strikes.
data.jw_atm_varFloatThe implied variance of the at-the-money options.
data.jw_slope_rightFloatThe slope of the volatility skew to the right (out-of-the-money calls).
data.jw_slope_leftFloatThe slope of the volatility skew to the left (out-of-the-money puts).
data.jw_atm_skewFloatThe skew of the at-the-money options, indicating the asymmetry of the volatility smile.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.10 Index Prices **Description:** Returns USD-denominated index prices for a given asset type. **Endpoints:** `/api/v1/price/index` \ **Method:** `POST` **Request Body:** ```json { "base_asset": "BTC", "asset_type": "future", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 5 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
base_assetStringtrueThe currency for which the index price is being requested. Please check the table for the Supported base assets.
asset_typeStringtrueThe type of asset. This can be "spot", "future" or "perpetual".
expiry*ISO 8601 stringtrueThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future".
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Note:** Fields marked \* are conditionally required (see field descriptions). **Response Data:** ```json { "data": [ { "v": 111370.49951, "timestamp": 1761811200000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the index price data and associated metadata.
data.vFloatThe index price value of the asset at the given timestamp.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.11 Mark Price **Description:** Returns USD-denominated mark prices for a given asset type. **Endpoints:** `/api/v1/price/mark`\ **Method:** `POST` **Request Body:** ```json { "base_asset": "BTC", "asset_type": "option", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "strike": [40000, 80000], "type": ["C", "P"], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
base_assetStringtrueThe currency for which the mark price is being requested. Please check the table for the Supported base assets.
asset_typeStringtrue

The type of asset.

This can be "spot", "future", "option" or "perpetual".

expiry*ISO 8601 string or StringtrueThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future" or "option". For option, the field can also accept constant tenors (Eg. "7d").
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
strike*List[Float] or Stringfalse

A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain an exchange's strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry. Note: In the case of strike endpoint "listed" should not be used when querying for arbitrary (non-listed) expiries, it is only valid for expiries that exist in the catalog. Eg. "strike":[3000, 3200] or "strike": "listed" . Non-listed / non-standard strikes are also supported when provided explicitly: "strike":[3280, 4255].

Mandatory only when asset_type="option"

type*List[str]false

List of option types to query.
Allowed values: "C" (Call), "P" (Put).

Mandatory only when asset_type="option"

frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "values": [ { "strike": 80000.0, "v": 30.9759, "type": "P" }, { "strike": 40000.0, "v": 0.046, "type": "P" }, { "strike": 40000.0, "v": 81498.1274, "type": "C" }, { "strike": 80000.0, "v": 41630.5538, "type": "C" } ], "timestamp": 1760025600000 } ] } ``` **Note:** Fields marked \* are conditionally required (see field descriptions). **Response Explanation:**
FieldTypeDescription
dataObjectContains the mark price data and associated metadata.
data.vFloatThe mark price value of the asset at the given timestamp.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.12 Mid Prices **Description:** Returns mid prices for a given asset type. **Endpoints:** `/api/v1/price/mid` \ **Method:** `POST` **Request Body:** ```json { "base_asset": "BTC", "asset_type": "option", "expiry": "2025-10-31T08:00:00:000Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 4 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
base_assetStringtrueThe currency for which the mid price is being requested. Please check the table for the Supported base assets.
asset_typeStringtrueThe type of asset. This can be "spot", "future", "option" or "perpetual".
expiry*ISO 8601 stringtrueThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future" or "option".
strike*List[Float] or Stringfalse

A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain an exchange's strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry. Note: In the case of strike endpoint "listed" should not be used when querying for arbitrary (non-listed) expiries, it is only valid for expiries that exist in the catalog. Eg. "strike":[3000, 3200] or "strike": "listed" . Non-listed / non-standard strikes are also supported when provided explicitly: "strike":[3280, 4255].

Mandatory only when asset_type="option"

type*List[str]false

List of option types to query.
Allowed values: "C" (Call), "P" (Put).

Mandatory only when asset_type="option"

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Note:** Fields marked \* are conditionally required (see field descriptions). **Response Data:** ```json { "data": [{ "v": 68234, "timestamp": 1717228800000 }, { "v": 68315, "timestamp": 1717232400000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the mid price data and associated metadata.
data.vFloatThe mid price value of the asset at the given timestamp.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.13 Settlement Prices (TWAP) **Description:** Returns the time weighted average spot index price as of the date of choice, or current \ time, whichever is sooner. The request can be made starting with 30m leading up to the \ specified expiry, denoting settlement datetime. The time weighting of the price is \ performed on the 31m worth of data leading up to settlement. **Endpoint:** `/api/v1/price/settlement`\ **Method:** `POST` **Request Body:** ```json { "currency": "BTC", "expiry": "2023-10-27T00:00:00.000Z", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 9 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
currencyStringtrueThe currency for which settlement price is being requested.
expiryISO 8601 stringtrueThe ISO datetime of settlement.
optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": { "v": 115537.321747493, "timestamp": 1761545520000, "expiry": 1761545520000, "currency": "BTC", "is_final": true } } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the settlement price data and associated metadata.
data.vFloatRepresents the time weighted average price at expiry or the current time, whichever is less.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded or the expiry time, whichever is less.
data.is_finalBooleanA boolean value indicating whether the settlement price data is considered final or not. This would be false if the request is made before or in the seconds immediately after the settlement datetime (expiry).
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.14 Forward Implied Rates **Description:** Returns forward-implied rates for supported assets. **Endpoint:** `/api/v1/rate/forward`\ **Method:** `POST` **Request Body:** ```json { "base_asset": "BTC", "exchange": "deribit", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 7 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
base_assetStringtrueThe currency for which the interest rate is being requested.
exchangeStringtrue

The name of the exchange from which to source market data.

Eg: "deribit", "blockscholes" etc.

"blockscholes": For data aggregated by BlockScholes, based on the futures index, which combines prices from multiple exchanges to produce a unified market feed.

expiryISO 8601 stringtrueThe expiry date and time for the asset in ISO 8601 format.
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "v": 1888, "timestamp": 1761555600000 }, { "v": 1625, "timestamp": 1761555600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the forward implied data and associated metadata.
data.vFloatRepresents the value of the asset at the given timestamp..
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.15 Funding Rates **Description:** Returns forward-implied rates for supported assets. **Endpoint:** `/api/v1/rate/funding`\ **Method:** `POST` **Request Body:** ```json { "base_asset": "BTC", "exchange": "deribit", "expiry": "2025-10-31T08:00:00Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 7 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
base_assetStringtrueThe currency for which the interest rate is being requested.
exchangeStringtrue

The name of the exchange from which to source market data.

Eg: "deribit", "blockscholes" etc.

"blockscholes": For data aggregated by BlockScholes, based on the futures index, which combines prices from multiple exchanges to produce a unified market feed.

startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string.
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Response Data:** ```json { "data": [ { "v": 1888, "timestamp": 1761555600000 }, { "v": 1625, "timestamp": 1761555600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the funding rates data and associated metadata.
data.vFloatRepresents the value of the asset at the given timestamp.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.16 Volume **Description:** Returns trading volume data for a given asset type across different exchanges. **Endpoint:** `/api/v1/analytic/volume`\ **Method:** `POST` **Request Body (Spot):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "spot", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Perpetual):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "perpetual", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Future):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "future", "expiry": "2025-12-26T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Option):** ```json { "exchange": "deribit", "base_asset": "BTC", "asset_type": "option", "expiry": "2025-12-26T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "strike": "listed", "frequency": "1h", "type": ["C"], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange from which to source trading volume data (e.g., "binance").
base_assetStringtrueThe currency for which the trading volume is being requested. Please check the table for the Supported base assets.
asset_typeStringtrue

The type of asset.

This can be "spot", "future", "option" or "perpetual".

expiry*ISO 8601 stringfalseThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future" or "option".
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
quote_assetStringtrueThe asset used as the pricing currency in a pair/market (e.g., USD in BTC/USD).
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

strike*List[Float] or Stringfalse

A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain an exchange's strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry. Eg. "strike":[3000, 3200] or "strike": "listed" .

Mandatory only when asset_type="option"

type*List[str]false

List of option types to query.
Allowed values: "C" (Call), "P" (Put).

Mandatory only when asset_type="option"

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":10
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Note:** Fields marked \* are conditionally required (see field descriptions). **Response Data (Spot):** ```json { "data": [ { "v": 0.00088, "timestamp": 1766235600000 } ] } ``` **Response Data (Perpetual):** ```json { "data": [ { "v": 5.0, "timestamp": 1766235600000 } ] } ``` **Response Data (Future):** ```json { "data": [ { "v": 1333.0, "timestamp": 1766235600000 } ] } ``` **Response Data (Option):** ```json { "data": [ { "values": [ { "strike": 92000.0, "v": 6.0, "type": "C" }, { "strike": 108000.0, "v": 2.0, "type": "C" } ], "timestamp": 1766232000000 }, { "values": [ { "strike": 160000.0, "v": 3.4, "type": "C" }, { "strike": 145000.0, "v": 1.5, "type": "C" } ], "timestamp": 1765857600000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the trading volume data and associated metadata.
data.vFloatThe trading volume value at the given timestamp. For spot, perpetuals, and futures, this represents the total volume traded. For options, it represents the number of contracts traded.
data.valuesListFor options only: contains strike-specific trading volume data when multiple strikes are requested or when using "listed" strikes.
data.values.strikeFloatThis represents the strike price.
data.values.vFloatThe trading volume for the specific instrument.
data.values.typeStringThe option type: "C" (Call) or "P" (Put).
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.17 Trade Price **Description:** Returns the last traded price for a given asset type across different exchanges. **Endpoint:** `/api/v1/price/trade`\ **Method:** `POST` **Request Body (Spot):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "spot", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Perpetual):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "perpetual", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Future):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "future", "expiry": "2025-12-26T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Option):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "option", "expiry": "2025-12-26T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "strike": "listed", "type": ["C"], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 0 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange from which to source trade price data (e.g., "binance").
base_assetStringtrueThe currency for which the trade price is being requested. Please check the table for the Supported base assets.
asset_typeStringtrue

The type of asset.

This can be "spot", "future", "option" or "perpetual".

expiry*ISO 8601 stringfalseThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future" or "option".
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
quote_assetStringtrueThe asset used as the pricing currency in a pair/market (e.g., USD in BTC/USD).
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

strike*List[Float] or Stringfalse

A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain an exchange's strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry. Eg. "strike":[3000, 3200] or "strike": "listed" .

Mandatory only when asset_type="option"

type*List[str]false

List of option types to query.
Allowed values: "C" (Call), "P" (Put).

Mandatory only when asset_type="option"

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":10
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Note:** Fields marked \* are conditionally required (see field descriptions). **Response Data (Spot):** ```json { "data": [ { "v": 88909.26, "timestamp": 1766386800000 } ] } ``` **Response Data (Perpetual):** ```json { "data": [ { "v": 88182.3, "timestamp": 1766221200000 } ] } ``` **Response Data (Future):** ```json { "data": [ { "v": 88382.7, "timestamp": 1766221200000 } ] } ``` **Response Data (Option):** ```json { "data": [ { "values": [ { "strike": 92000.0, "v": 1970.0, "type": "C" }, { "strike": 80000.0, "v": 11300.0, "type": "C" } ], "timestamp": 1766221200000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataArrayContains the trade price data and associated metadata. Returns an array of data points, one per timestamp.
data.vFloatThe last traded price at the given timestamp. For spot, perpetuals, and futures, this represents the most recent transaction price. For options, it represents the last trade price for the specific contract.
data.valuesArrayFor options only: contains strike-specific trade price data when multiple strikes are requested or when using "listed" strikes.
data.values.strikeFloatThe strike price of the option contract.
data.values.vFloatThe last traded price for the specific instrument.
data.values.typeStringThe option type: "C" (Call) or "P" (Put).
data.timestampIntegerAn integer value representing the timestamp when the trade occurred.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
### 4.18 Open-Interest (OI) **Description:** Returns open interest data for a given asset type across different exchanges. **Endpoint:** `/api/v1/analytic/oi`\ **Method:** `POST` **Request Body (Perpetual):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "perpetual", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Future):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "future", "expiry": "2026-03-27T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Option):** ```json { "exchange": "deribit", "base_asset": "BTC", "asset_type": "option", "expiry": "2026-01-30T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USDC", "strike":[116000.0], "type": ["C"], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange from which to source open-interest data (e.g., "binance").
base_assetStringtrueThe currency for which the open-interest is being requested. Please check the table for the Supported base assets.
asset_typeStringtrue

The type of asset.

This can be "perpetual", "future" or "option".

expiry*ISO 8601 stringfalseThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future" or "option".
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
quote_assetStringtrueThe asset used as the pricing currency in a pair/market (e.g., USD in BTC/USD).
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

strike*List[Float] or Stringfalse

A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain an exchange's strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry. Eg. "strike":[3000, 3200] or "strike": "listed" .

Mandatory only when asset_type="option"

type*List[str]false

List of option types to query.
Allowed values: "C" (Call), "P" (Put).

Mandatory only when asset_type="option"

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":10
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Note:** Fields marked \* are conditionally required (see field descriptions). **Response Data (Perpetual):** ```json { "data": [ { "v": 18469444.0, "timestamp": 1767960000000 } ] } ``` **Response Data (Future):** ```json { "data": [ { "v": 2156515.0, "timestamp": 1767960000000 } ] } ``` **Response Data (Option):** ```json { "data": [ { "values": [ { "strike": 116000.0, "v": 0.0, "type": "C" } ], "timestamp": 1767960000000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataObjectContains the open-interest data and associated metadata.
data.vFloatRepresents the number of outstanding derivative contracts that have not been closed or settled. This applies to futures, perpetuals, and options.
data.valuesListFor options only: contains strike-specific open-interest data when multiple strikes are requested or when using "listed" strikes.
data.values.strikeFloatThis represents the strike price.
data.values.vFloatThe open-interest for the specific instrument.
data.values.typeStringThe option type: "C" (Call) or "P" (Put).
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ### 4.19 Quote Price **Description:** Returns quote data (bid and ask) for a given asset type across different exchanges. **Endpoint:** `/api/v1/price/quote`\ **Method:** `POST` **Request Body (Spot):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "spot", "start": "LATEST", "end": "LATEST", "quote_asset": "USDC", "data_types": ["price", "size"], "frequency": "1m", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Perpetual):** ```json { "exchange": "binance", "base_asset": "BTC", "asset_type": "perpetual", "start": "LATEST", "end": "LATEST", "frequency": "1m", "quote_asset": "USDC", "data_types": ["price", "size"], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Future):** ```json { "exchange": "deribit", "base_asset": "BTC", "asset_type": "future", "expiry": "2026-03-27T08:00:00Z", "start": "LATEST", "end": "LATEST", "quote_asset": "USD", "data_types": ["price", "size"], "frequency": "1h", "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 10 } } } ``` **Request Body (Option):** ```json { "exchange": "deribit", "base_asset": "BTC", "asset_type": "option", "expiry": "2026-01-30T08:00:00Z", "start": "LATEST", "end": "LATEST", "frequency": "1h", "quote_asset": "USDC", "data_types": ["price", "size"], "strike": [85000.0], "type": ["C","P"], "options": { "format": { "timestamp": "ms", "hexify": false, "decimals": 0 } } } ``` **Request Explanation:**
FieldTypeMandatoryDescription
exchangeStringtrueThe name of the exchange from which to source quote data (e.g., "binance").
base_assetStringtrueThe currency for which the quote data is being requested. Please check the table for the Supported base assets.
asset_typeStringtrue

The type of asset.

This can be "spot", "future", "option" or "perpetual".

data_typesList[String]trueTypes of quote data to return. Allowed values: "price", "size". If not provided Default: ["price"].
expiry*ISO 8601 stringfalseThe expiry date and time for the asset in ISO 8601 format. Required if the asset type is "future" or "option".
startStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
endStringfalseDefault value is "LATEST" to get the latest values. Also accepts ISO 8601 string for historical data queries.
quote_assetStringtrueThe asset used as the pricing currency in a pair/market (e.g., USD in BTC/USD).
frequencyStringfalse

Defines the time interval between data points in the response.

Possible values:

  • 1h - Hourly data
  • 1m - Minutely data

Default: 1h (hourly data)

strike*List[Float] or Stringfalse

A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain an exchange's strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry. Eg. "strike":[3000, 3200] or "strike": "listed" .

Mandatory only when asset_type="option"

type*List[str]false

List of option types to query.
Allowed values: "C" (Call), "P" (Put).

Mandatory only when asset_type="option"

optionsObjecttrueDefines custom configuration options for the API response.
options.formatObjecttrueSpecifies data formatting preferences for the response.
options.format.timestampStringtrueDefines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds). Message timestamps are always integers.
options.format.hexifyBooleantrueWhether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.
options.format.decimalsIntegertrueNumber of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled accordingly. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":10
options.signatureObjectfalseContains information about the signature domain specified by the client. Please check EIP-712 Signatures.
**Note:** Fields marked \* are conditionally required (see field descriptions). **Response Data: (Spot)** ```json { "data": [ { "timestamp": 1768986000000, "bid": 89115.31, "ask": 89115.32, "bid_size": 0.38412, "ask_size": 0.34933 } ] } ``` **Response Data: (Perpetual)** ```json { "data": [ { "timestamp": 1768986000000, "bid": 89077.0, "ask": 89077.1, "bid_size": 0.477, "ask_size": 0.567 } ] } ``` **Response Data: (Future)** ```json { "data": [ { "timestamp": 1768978800000, "bid": 90295.0, "ask": 90297.5, "bid_size": 3700.0, "ask_size": 200.0 } ] } ``` **Response Data: (Option)** ```json { "data": [ { "values": [ { "strike": 85000.0, "type": "P", "bid": 575.0, "ask": 615.0, "bid_size": 5.0, "ask_size": 2.45 }, { "strike": 85000.0, "type": "C", "bid": 5.0, "ask": 14000.0, "bid_size": 3.24, "ask_size": 0.1 } ], "timestamp": 1767956400000 } ] } ``` **Response Explanation:**
FieldTypeDescription
dataArrayContains the quote price data and associated metadata.
data.vFloatThe quote price value (bid or ask) of the asset at the given timestamp.
data.timestampIntegerAn integer value representing the timestamp when the data was recorded.
data.valuesArrayFor options: Contains an array of quote data for each strike and option type combination.
data.values.strikeFloatThe strike price of the option.
data.values.typeStringThe option type: "C" (Call) or "P" (Put).
data.values.bidFloatThe best bid price available for the specific instrument.
data.values.askFloatThe best ask price available for the specific instrument.
data.values.bid_sizeFloatAvailable quantity/size at the best bid price.
data.values.ask_sizeFloatAvailable quantity/size at the best ask price.
signatureObjectThe signature field contains the EIP-712 signature, enabling on-chain validation of data integrity, and serving as a confirmation of authenticity & data quality as provided by Block Scholes.
*** ## 5. Error Handling **Error Messages**
Error TypeHTTP CodeExample BodyDescription
Authentication Error403
{
"data": {},
"error": {
"message": "Forbidden"
    }
}

Occurs when an invalid or missing API key is provided in the request header. Ensure that a valid X-API-Key is included.
Missing Required Field422
{ 
"data": {}, 
"error": { 
"message": "Invalid parameters: 'exchanges': Field required" 
    } 
}

Triggered when required fields are omitted from the request body. Check all mandatory parameters.
Validation Error422
{
"data": {},
"error": {
"message": "Validation error: exchange should be provided"
    }
}

Occurs when request parameters fail validation (e.g., missing exchange or invalid parameter types).
Data Not Found Error404
{
"data": {},
"error": {
"message": "No timeseries data retrieved. Errors: No instrument found matching the specified criteria"
    }
}

Indicates that no data was found for the provided filters or date range. Verify the start, end, or filtering parameters.
Internal Server Error 500
{
"data": {},
"error": {
"message": "Internal     server error"
    }
}

A generic error indicating a server-side issue. Retry later or report the incident.
*** ## **6. Supported Base Assets**
asset_typebase_assets
option

To fetch all the allowed currencies for the option asset_type, please use the catalog API with 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"],
    "base_assets":[]
}
spot

To fetch all the allowed currencies for the spot asset_type, please use the catalog API with 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":["spot"],
    "base_assets":[]
}
perpetual

To fetch all the allowed currencies for the spot asset_type, please use the catalog API with 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":["perpetual"],
    "base_assets":[]
}
future

To fetch all the allowed currencies for the spot asset_type, please use the catalog API with 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/rest-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.