REST API

Block Scholes API covering historical and recent digital asset data.

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

Catalog of instruments listed on specified exchanges.

1.2 Implied Volatility Surface

Category

Endpoint

Description

IV by Strike

/api/v1/iv/strike

Implied volatility for given strike prices.

IV by Delta

/api/v1/iv/delta

Implied volatility for specified delta levels.

IV by Moneyness

/api/v1/iv/moneyness

Implied volatility for specified moneyness levels.

IV by Risk Reversal (Call-Put Skew)

/api/v1/iv/risk-reversal

Risk reversal data derived from the implied volatility surface.

IV by Butterfly Spread

/api/v1/iv/butterfly-spread

Butterfly spread data derived from the implied volatility surface.

IV Index (BSIV)

/api/v1/iv/index

The Block Scholes Implied Volatility Index (BSIV) for constant tenors.

Calibrated Model Parameters

/api/v1/modelparams

Calibrated SVI model parameters for a given exchange and expiry.

1.3 Instrument Pricing

Category

Endpoint

Description

Index Price

/api/v1/price/index

Index price for a specified asset type.

Mark Price

/api/v1/price/mark

Mark price for a specified asset type.

Mid Price

/api/v1/price/mid

Mid-price for a given instrument.

Settlement Price

/api/v1/price/settlement

Time-weighted spot index price at or before expiry.

1.4 Market Data

Data Type

Endpoint

Description

Forward-Implied Rates

/api/v1/rate/forward

Forward-implied rates for supported assets.

Funding Rates

/api/v1/rate/funding

Perpetual funding rates.

Treasury Rates

/api/v1/rate/treasury

Treasury yield curve daily (bank discount) rates for supported maturities.

Quote Prices (BBO)

/api/v1/price/quote

Best bid & ask for respective instrument

Trade Price

/api/v1/price/trade

Last traded price for respective instrument

Open Interest

/api/v1/analytic/oi

Returns aggregated open interest across supported exchanges.

Trade Volume

/api/v1/analytic/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

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:

{
    "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

Field

Type

Mandatory

Description

format

Object

Specifies data formatting preferences for the response.

format.timestamp

String

Defines the precision of the timestamps attached to returned data responses. Valid values: "s" (seconds), "ms" (milliseconds), "ns" (nanoseconds).

format.hexify

Boolean

Whether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.

format.decimals

Integer

Number of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled by 10^decimals. When no signing is requested, numerical values will be rounded to the specified number of decimals. Eg.: "decimals":9

signature

Object

Contains 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 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:

{
    "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:

Field

Type

Mandatory

Description

start

ISO 8601 string

An instrument is considered valid if it expires after the specified "start" date.

end

ISO 8601 string

An instrument is considered valid if it is listed before the specified "end" date.

exchanges

List[str]

List of exchanges for filtering Catalog instruments. Eg. "blockscholes".

asset_types

List[str]

List of asset types for filtering Catalog instruments. Valid types are 'option', 'future', 'spot', 'perpetual'.

base_assets

List[str]

List of base assets for filtering Catalog instruments. Please check the table for the Supported base assets.

quote_assets

List[str]

Optional list of quote assets for filtering Catalog instruments.

fields

List[str]

Optional 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

{ 
   "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:

Field

Type

Description

data

List

List of Catalog Instruments that match the filters in the request.

asset_type

String

Represents the asset type of the instrument.

exchange

String

Represents the exchange associated with the instrument.

available_since

ISO 8601 string

The date and time when the instrument was made available.

listing

ISO 8601 string

The date and time when the instrument was listed.

base_asset

String

The base asset of the instrument.

quote_asset

String

The quote asset of the instrument.

settlement_asset

String

The settlement asset of the instrument.

expiry

ISO 8601 string

The date and time when the instrument expires. Only available for future and option asset types.

strike

Integer

An integer indicating the strike price of the option. Only available for option asset type.

type

String

Represents the type of the option. 'C' for call options and 'P' for put options. Only available for option asset type.

style

String

Represents 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:

{
    "feed": {
        "name": "index.px"
    },
    "base_asset": "BTC",
    "asset_type": "spot"
}

Request Explanation:

Field

Type

Mandatory

Description

feed

Object

Defines the feed metadata.

feed.name

String

The name of the feed Eg. mark.px, index.px.

base_asset

String

The currency to be added to the provided feed. Please check the table for the Supported base assets.

asset_type

String

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

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

Response Data

{
    "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:

{
    "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:

Response Data:

{
    "data": [
        {
            "values": [
                {
                    "strike": 200000.0,
                    "v": 1.67449
                },
                {
                    "strike": 100000.0,
                    "v": 0.86181
                }
            ],
            "timestamp": 1761807600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the implied volatility data and associated metadata.

data.values

List

Each object inside the values list has the following fields: (strike, v)

data.values.strike

Float

This represents the strike price.

data.values.v

Float

This represents the implied volatility value for the given strike price.

data.timestamp

Float

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [
        {
            "values": [
                {
                    "delta": 0.5,
                    "v": 0.66
                },
                {
                    "delta": 0.1,
                    "v": 0.72
                }
            ],
            "timestamp": 1761807600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the implied volatility data and associated metadata.

data.values

List

Each object inside the values list has the following fields: (delta, v)

data.values.delta

Float

This represents the delta level of the IV.

data.values.v

Float

This represents the implied volatility value.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{ 
    "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:

Response Data:

{
    "data": [
        {
            "values": [
                {
                    "money": 1.0,
                    "v": 0.6661
                },
                {
                    "money": 2.0,
                    "v": 2.16117
                }
            ],
            "timestamp": 1761807600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the implied volatility data and associated metadata.

data.values

List

Each object inside the values list has the following fields: (moneyness, v)

data.values.moneyness

Float

This represents the moneyness level of the IV.

data.values.v

Float

This represents the implied volatility value.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [
        {
            "values": [
                {
                    "delta": 0.1,
                    "v": -0.1112160081
                },
                {
                    "delta": 0.2,
                    "v": -0.0957562627
                },
                {
                    "delta": 0.25,
                    "v": -0.0823526868
                }
            ],
            "timestamp": 1761807600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the implied volatility data and associated metadata.

data.values

List

Each object inside the values list has the following

fields: (delta, v)

data.values.delta

Float

This represents the delta level of the IV.

data.values.v

Float

This represents the implied volatility value.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [
        {
            "values": [
                {
                    "delta": 0.1,
                    "v": 0.1055129515
                },
                {
                    "delta": 0.2,
                    "v": 0.0439171329
                },
                {
                    "delta": 0.25,
                    "v": 0.0274426774
                }
            ],
            "timestamp": 1761807600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the implied volatility data and associated metadata.

data.values

List

Each object inside the values list has the following

fields: (delta, v)

data.values.delta

Float

This represents the delta level of the IV.

data.values.v

Float

This represents the implied volatility value.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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 IV Index

Description: Returns a composite implied volatility index for a given asset and tenor.

Endpoint: /api/v1/iv/index Method: POST

Request Body:

{ 
    "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:

Response Data:

{
    "data": [
        {
            "v": 47.8669535559,
            "timestamp": 1761807600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the implied volatility index data and associated metadata.

data.v

Float

This represents the implied volatility index vol value.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "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:

Field

Type

Description

data

Object

Contains the model parameter data and associated metadata.

data.alpha

Float

Controls the overall level of total variance.

data.beta

Float

Controls the skewness of the variance smile.

data.rho

Float

Controls the rotation of the smile.

data.m

Float

Controls the horizontal translation of the smile.

data.sigma

Float

Controls atm curvature of the smile.

data.jw_atm_total_var

Float

The total variance of the at-the-money options.

data.jw_min_imp_var

Float

The minimum implied variance across all strikes.

data.jw_atm_var

Float

The implied variance of the at-the-money options.

data.jw_slope_right

Float

The slope of the volatility skew to the right (out-of-the-money calls).

data.jw_slope_left

Float

The slope of the volatility skew to the left (out-of-the-money puts).

data.jw_atm_skew

Float

The skew of the at-the-money options, indicating the asymmetry of the volatility smile.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [
        {
            "v": 111370.49951,
            "timestamp": 1761811200000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the index price data and associated metadata.

data.v

Float

The index price value of the asset at the given timestamp.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "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
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the mark price data and associated metadata.

data.v

Float

The mark price value of the asset at the given timestamp.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [{
            "v": 68234,
            "timestamp": 1717228800000
        }, {
            "v": 68315,
            "timestamp": 1717232400000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the mid price data and associated metadata.

data.v

Float

The mid price value of the asset at the given timestamp.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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

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:

{
    "currency": "BTC",
    "expiry": "2023-10-27T00:00:00.000Z",
    "options": {
        "format": {
            "timestamp": "ms",
            "hexify": false,
            "decimals": 9
        }
    }
}

Request Explanation:

Field

Type

Mandatory

Description

currency

String

The currency for which settlement price is being requested.

expiry

ISO 8601 string

The ISO datetime of settlement.

options

Object

Defines custom configuration options for the API response.

options.format

Object

Specifies data formatting preferences for the response.

options.format.timestamp

String

Defines 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.hexify

Boolean

Whether to convert numeric values to hexadecimal. If enabled, all numeric values will be transmitted as hex strings.

options.format.decimals

Integer

Number of decimals to support for numerical types in the data. Eg.: "decimals":9

options.signature

Object

Contains information about the signature domain specified by the client.

Response Data:

{
    "data": {
        "v": 115537.321747493,
        "timestamp": 1761545520000,
        "expiry": 1761545520000,
        "currency": "BTC",
        "is_final": true
    }
}

Response Explanation:

Field

Type

Description

data

Object

Contains the settlement price data and associated metadata.

data.v

Float

Represents the time weighted average price at expiry or the current time, whichever is less.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded or the expiry time, whichever is less.

data.is_final

Boolean

A 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).

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [
        {
            "v": 1888,
            "timestamp": 1761555600000
        },
        {
            "v": 1625,
            "timestamp": 1761555600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the forward implied data and associated metadata.

data.v

Float

Represents the value of the asset at the given timestamp..

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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:

{
    "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:

Response Data:

{
    "data": [
        {
            "v": 1888,
            "timestamp": 1761555600000
        },
        {
            "v": 1625,
            "timestamp": 1761555600000
        }
    ]
}

Response Explanation:

Field

Type

Description

data

Object

Contains the funding rates data and associated metadata.

data.v

Float

Represents the value of the asset at the given timestamp.

data.timestamp

Integer

An integer value representing the timestamp when the data was recorded.

signature

Object

The 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 Type

HTTP Code

Example Body

Description

Authentication Error

403

{
"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 Field

422

{ 
"data": {}, 
"error": { 
"message": "Invalid parameters: 'exchanges': Field required" 
    } 
}

Triggered when required fields are omitted from the request body. Check all mandatory parameters.

Validation Error

422

{
"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 Error

404

{
"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_type

base_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":[]
}

NextWebSocket API

Last updated 51 minutes ago