WebSocket API
Block Scholes API covering real-time digital asset data
Connection URL: wss://prod-websocket-api.blockscholes.com/
1. Subscription Feeds Overview
1.1 Instrument Pricing
Feed Type
Feed Name
Description
1.2 Implied Volatility Surface
Feed Type
Feed Name
Description
1.3 Market Data
Feed Type
Feed Name
Description
2. Authentication
Connections must be authenticated before any subscriptions can be made. The API follows the JSON RPC 2.0 standard. Reach out for a free API key
2.1 Using API Key
Description: Authenticates the WebSocket connection using an API key.
Method: authenticate
Request:
{
"jsonrpc": "2.0",
"method": "authenticate",
"params": {
"api_key": "xxx"
}
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
The method name. Must be "authenticate".
params
Object
Parameters object containing authentication credentials.
params.api_key
String
Your API key for authentication.
Response (Success):
{
"jsonrpc": "2.0",
"result": "ok"
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
String
Authentication result. "ok" indicates success.
3. Subscription Configuration
3.1 Batching
Batching allows receiving multiple datapoints together in a single message.
Batching Rules:
Updates are sent only if values change. This means different batches may contain different subsets of datapoints of the total subscribed for.
Batch frequency defines maximum publishing rate. Actual publish rate differs based on underlying datatype calculation frequency.
Default limit: 10 items per batch (adjustable).
Key Batch Parameters:
frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms etc
client_id
String
Optional identifier for the subscription
batch
Array
Array of subscription entry parameters
batch[i].sid
String
Identifier for a batch subscription entry
3.2 EIP-712 Signing
Signing with EIP-712 signatures is supported for update messages as an optional feature, allowing integrity & provenance verification on-chain.
To enable, include the signature configuration along with domain information in the subscription request.
For type definitions and detailed verification schema, refer to the Pull Oracle documentation section.
Example with EIP-712 Signature:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [
{
"frequency": "1000ms",
"batch": [ ... ],
"options": {
"format": {
"timestamp": "ms",
"hexify": true,
"decimals": 9
},
"signature": {
"domain": {
"name": "TRIAL",
"version": "1",
"chain_id": "50000",
"verifying_contract": "0x1111111111111111111111111111111111111111"
}
}
}
}
]
}3.3 Formatting Options
The options.format object allows customization of data formatting in subscription responses.
timestamp
String
Timestamp precision. Valid values: s (seconds), ms (milliseconds), ns (nanoseconds)
hexify
Boolean
If enabled, all numeric values will be transmitted as hex strings.
decimals
Integer or Object
Number of decimals to support for numerical types in the data. When signing is requested, numerical values will be scaled by 10decimals. When no signing is requested, numerical values will be rounded to the specified number of decimals. Integer applies to entire batch. Object allows per-sid precision (e.g., {"0x1": 9, "0x2": 5})
4. Subscription Feeds
4.1 Mark Price
Description: Streams live mark prices for specified instruments. Futures and options support any expiry of choice, and options support any strike of choice as well, allowing user to price any instrument.
Feed Name: mark.px
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "1000ms",
"client_id": "mark_subscription_1",
"batch": [{
"sid": "0x1",
"feed": "mark.px",
"asset": "option",
"base_asset": "BTC",
"quote_asset": "USD",
"model": "SVI",
"strike": 100000,
"type": "C",
"expiry": "2025-12-26T08:00:00Z"
}, {
"sid": "0x2",
"feed": "mark.px",
"asset": "perpetual",
"base_asset": "BTC",
"quote_asset": "USD"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 4
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be mark.px.
params.batch.asset
String
Asset type. Valid values: option, future, perpetual, spot.
params.batch.base_asset
String
The currency to be added to the provided feed. Please check the table for the Supported base assets.
params.batch.quote_asset
String
Quote asset (e.g., USD). Default: USD.
params.batch.model
String
The mathematical model used to fit market quotes and interpolate or extrapolate values. Allowed values:
SVI
Spline
Default: SVI.
Required for "options".
params.batch.strike
Integer/Float
Strike price. Required if asset is option.
params.batch.type
String
Option type. Valid values: C (Call), P (Put). Required if asset is option.
params.batch.expiry
ISO 8601 string
Expiry date/time. Required if asset is option or future.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "1000ms",
"client_id": "mark_subscription_1",
"batch": [{
"sid": "0x1",
"feed": "mark.px",
"asset": "option",
"base_asset": "BTC",
"quote_asset": "USD",
"model": "SVI",
"strike": 100000,
"type": "C",
"expiry": "2025-12-26T08:00:00Z"
}, {
"sid": "0x2",
"feed": "mark.px",
"asset": "perpetual",
"base_asset": "BTC",
"quote_asset": "USD"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 4
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "0x1",
"v": 9561.1178
}, {
"sid": "0x2",
"v": 103928.0873
}
],
"timestamp": 1762261424000
},
"client_id": "mark_subscription_1"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The mark price value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.2 Index Price
Description: Streams real-time USD-denominated index prices for specified assets.
Feed Name: index.px
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "1000ms",
"client_id": "index_subscription_1",
"batch": [{
"sid": "idx_1",
"feed": "index.px",
"asset": "spot",
"base_asset": "BTC",
"quote_asset": "USD"
}, {
"sid": "idx_2",
"feed": "index.px",
"asset": "future",
"base_asset": "ETH",
"quote_asset": "USD",
"expiry": "2025-12-26T08:00:00Z"
}, {
"sid": "idx_3",
"feed": "index.px",
"asset": "perpetual",
"exchange": "blockscholes",
"base_asset": "BTC"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be index.px.
params.batch.asset
String
Asset type. Valid values: spot, future, perpetual.
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.quote_asset
String
Quote asset (e.g., USD). Default: USD.
params.batch.expiry
ISO 8601 string
Expiry date/time. Required if asset is future.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "1000ms",
"client_id": "index_subscription_1",
"batch": [{
"sid": "idx_1",
"feed": "index.px",
"asset": "spot",
"base_asset": "BTC",
"quote_asset": "USD"
}, {
"sid": "idx_2",
"feed": "index.px",
"asset": "future",
"base_asset": "ETH",
"quote_asset": "USD",
"expiry": "2025-12-26T08:00:00Z"
}, {
"sid": "idx_3",
"feed": "index.px",
"asset": "perpetual",
"exchange": "blockscholes",
"base_asset": "BTC"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "idx_1",
"v": 103940.45269
}, {
"sid": "idx_2",
"v": 3518.75082
}, {
"sid": "idx_3",
"v": 103899.29266
}
],
"timestamp": 1762261149500
},
"client_id": "index_subscription_1"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The index price value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.3 Settlement Price
Description: Streams real-time time-weighted spot index price at or before the specified expiry. The time weighting of the price is performed on the 31m worth of data leading up to settlement.
Feed Name: settlement.px
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "1000ms",
"client_id": "settlement_subscription_1",
"batch": [{
"sid": "0x01",
"feed": "settlement.px",
"expiry": "2025-12-26T20:00:00Z",
"base_asset": "AAVE"
}, {
"sid": "0x02",
"feed": "settlement.px",
"expiry": "2025-12-14T17:55:00Z",
"base_asset": "SOL"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 9
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be settlement.px.
params.batch.expiry
ISO 8601 string
Settlement expiry date/time.
params.batch.base_asset
String
The base asset (ie. BTC)
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "1000ms",
"client_id": "settlement_subscription_1",
"batch": [{
"sid": "0x01",
"feed": "settlement.px",
"expiry": "2025-12-26T20:00:00Z",
"base_asset": "AAVE"
}, {
"sid": "0x02",
"feed": "settlement.px",
"expiry": "2025-12-14T17:55:00Z",
"base_asset": "SOL"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 9
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
id
Integer/String
The same identifier from the request.
result
Array
Array containing subscription confirmation objects.
result.batch
Object
Echo of the complete subscription configuration.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "0x01",
"v": 115537.32174749
}, {
"sid": "0x02",
"v": 185.432156789,
}
],
"timestamp": 1762259941000
},
"client_id": "settlement_subscription_1"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The time-weighted average settlement price value.
params.data.values.is_final
Boolean
Indicates whether the settlement price is final. False if the request is made before or in the seconds immediately after the settlement datetime (expiry).
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.4 Implied Volatility by Strike
Description: Streams real-time implied volatility values at specific strike levels. The expiry and strike fields can take arbitrary values, enabling users to pick any point on the underlying volatility surface.
Feed Name: strike.iv
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "1000ms",
"client_id": "strike_iv_1",
"batch": [{
"sid": "s1",
"feed": "strike.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"strike": [100000],
"expiry": "2025-12-26T08:00:00Z"
}, {
"sid": "s2",
"feed": "strike.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"strike": [200000],
"expiry": "2025-12-14T08:00:00Z"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be strike.iv.
params.batch.exchange
String
Exchange name (e.g., composite, deribit).
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.model
String
Model type. Valid values: SVI, Spline. Default: SVI.
params.batch.strike
String, Integer/Float, List[Float]
A list of strikes found on the given exchange (please refer to our catalog endpoint to obtain exchange-specific strikes), or "listed" to include all strikes currently listed on the exchange for the given expiry.
params.batch.expiry
ISO 8601 string
Expiry date/time.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "1000ms",
"client_id": "strike_iv_1",
"batch": [{
"sid": "s1",
"feed": "strike.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"strike": [100000],
"expiry": "2025-12-26T08:00:00Z"
}, {
"sid": "s2",
"feed": "strike.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"strike": [200000],
"expiry": "2025-12-14T08:00:00Z"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "s1",
"strike": [100000.0],
"v": [0.46222]
}, {
"sid": "s2",
"strike": [200000.0],
"v": [0.64501]
}
],
"timestamp": 1762259615500
},
"client_id": "strike_iv_1"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The implied volatility value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.5 Implied Volatility by Delta
Description: Streams real-time implied volatility values for specified delta levels. The expiry and delta fields can take arbitrary values, enabling users to pick any point on the underlying volatility surface.
Feed Name: delta.iv
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [
{
"frequency": "20000ms",
"client_id": "BS_DELTA_TEST",
"batch": [
{
"sid": "0x101",
"feed": "delta.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"expiry": "2025-12-26T08:00:00Z",
"delta": [0.5, 0.45, 0.1]
},
{
"sid": "0x102",
"feed": "delta.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"expiry": "2025-12-14T08:00:00Z",
"delta": [0.2, 0.3]
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be delta.iv.
params.batch.exchange
String
Exchange name (e.g., composite, deribit).
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.model
String
Model type. Valid values: SVI, Spline. Default: SVI.
params.batch.delta
Float
Delta level. Valid values include: 0.5, 0.45, 0.40, 0.35, 0.30, 0.25, 0.20, 0.15, 0.10, 0.05, 0.04, 0.03, 0.02, 0.01 (both positive and negative).
params.batch.expiry
ISO 8601 string
Expiry date/time.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "20000ms",
"client_id": "BS_DELTA_TEST",
"batch": [{
"sid": "0x101",
"feed": "delta.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"expiry": "2025-12-26T08:00:00Z",
"delta": [0.5, 0.45, 0.1]
}, {
"sid": "0x102",
"feed": "delta.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"expiry": "2025-12-14T08:00:00Z",
"delta": [0.2, 0.3]
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "0x101",
"delta": [0.1, 0.45, 0.5],
"v": [0.46448, 0.43855, 0.44285]
}, {
"sid": "0x102",
"delta": [0.2, 0.3],
"v": [0.42911, 0.42306]
}
],
"timestamp": 1762258729500
},
"client_id": "BS_DELTA_TEST"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The implied volatility value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.6 Implied Volatility by Moneyness
Description: Streams real-time implied volatility values at given moneyness ratios (strike/forward). The expiry and moneyness fields can take arbitrary values, enabling users to pick any point on the underlying volatility surface.
Feed Name: moneyness.iv
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "20000ms",
"client_id": "BS_MONEYNESS_TEST",
"batch": [{
"sid": "0x101",
"feed": "moneyness.iv",
"exchange": "composite",
"base_asset": "ETH",
"model": "SVI",
"expiry": "2025-12-14T08:00:00Z",
"moneyness": [0.5, 2, 1]
}, {
"sid": "0x102",
"feed": "moneyness.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"expiry": "30d",
"moneyness": [0.5, 2, 1]
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be moneyness.iv.
params.batch.exchange
String
Exchange name (e.g., composite, deribit).
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.model
String
Model type. Valid values: SVI, Spline. Default: SVI.
params.batch.moneyness
Float
Moneyness level. Valid values range from 0.1 to 3.0.
params.batch.expiry
ISO 8601 string
Expiry date/time.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "20000ms",
"client_id": "BS_MONEYNESS_TEST",
"batch": [{
"sid": "0x101",
"feed": "moneyness.iv",
"exchange": "composite",
"base_asset": "ETH",
"model": "SVI",
"expiry": "2025-12-14T08:00:00Z",
"moneyness": [0.5, 2, 1]
}, {
"sid": "0x102",
"feed": "moneyness.iv",
"exchange": "composite",
"base_asset": "BTC",
"model": "SVI",
"expiry": "30d",
"moneyness": [0.5, 2, 1]
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "0x101",
"moneyness": [1.0, 2.0, 0.5],
"v": [0.68182, 0.87968, 1.03505]
}, {
"sid": "0x102",
"moneyness": [1.0, 2.0, 0.5],
"v": [0.43735, 0.75756, 0.82217]
}
],
"timestamp": 1762258013000
},
"client_id": "BS_MONEYNESS_TEST"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The implied volatility value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.7 IV Index (BSIV)
Description: Streams real-time Block Scholes Implied Volatility Index (BSIV) for constant tenors.
Feed Name: index.iv
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [
{
"frequency": "1000ms",
"client_id": "BS_INDEX_IV_TEST",
"batch": [
{
"sid": "90d",
"feed": "index.iv",
"exchange": "composite",
"base_asset": "ETH",
"expiry": "90d"
},
{
"sid": "30d",
"feed": "index.iv",
"exchange": "composite",
"base_asset": "ETH",
"expiry": "30d"
},
{
"sid": "7d",
"feed": "index.iv",
"exchange": "composite",
"base_asset": "ETH",
"expiry": "7d"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be index.iv.
params.batch.exchange
String
Exchange name (e.g., composite).
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.expiry
String
Constant tenor (e.g., 7d, 30d, 90d).
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "1000ms",
"client_id": "BS_INDEX_IV_TEST",
"batch": [{
"sid": "90d",
"feed": "index.iv",
"exchange": "composite",
"base_asset": "ETH",
"model": "SVI",
"expiry": "90d"
}, {
"sid": "30d",
"feed": "index.iv",
"exchange": "composite",
"base_asset": "ETH",
"model": "SVI",
"expiry": "30d"
}, {
"sid": "7d",
"feed": "index.iv",
"exchange": "composite",
"base_asset": "ETH",
"model": "SVI",
"expiry": "7d"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 5
}
}
}
}
]
}
Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"v": 72.37018,
"sid": "90d"
}, {
"v": 74.15651,
"sid": "30d"
}, {
"v": 76.38079,
"sid": "7d"
}
],
"timestamp": 1762257552500
},
"client_id": "BS_INDEX_IV_TEST"
}
]
}
Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The IV index value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.8 Model Parameters
Description: Streams real-time calibrated model parameters for the given exchange and expiry.
Feed Name: model.params
Method: subscribe
Important Notes:
Model Parameters cannot be mixed with other data types in the same batch.
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "20000ms",
"client_id": "model_params_1",
"batch": [{
"sid": "mp_1",
"feed": "model.params",
"exchange": "composite",
"asset": "option",
"base_asset": "BTC",
"model": "SVI",
"expiry": "2025-12-26T08:00:00Z"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 4
}
}
}
]
}Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.client_id
String
Optional identifier for this subscription.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be model.params.
params.batch.exchange
String
Exchange name. Eg., "composite"
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.asset
String
Supports "option" asset
params.batch.model
String
Model type. Default: SVI.
params.batch.expiry
ISO 8601 string
Expiry date/time.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "20000ms",
"client_id": "model_params_1",
"batch": [{
"sid": "mp_1",
"feed": "model.params",
"exchange": "composite",
"asset": "option",
"base_asset": "BTC",
"model": "SVI",
"expiry": "2025-12-26T08:00:00Z"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 4
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "mp_1",
"alpha": 0.0099,
"beta": 0.0864,
"rho": -0.0054,
"m": 0.0939,
"sigma": 0.1935
}
],
"timestamp": 1762251931000
},
"client_id": "model_params_1"
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.alpha
Float
Controls the overall level of total variance.
params.data.values.beta
Float
Controls the skewness of the variance smile.
params.data.values.rho
Float
Controls the rotation of the smile.
params.data.values.m
Float
Controls the horizontal translation of the smile.
params.data.values.sigma
Float
Controls atm curvature of the smile.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.9 Interest Rates
Description: Streams real-time forward-implied interest rates for supported assets. Supports any expiry of choice, allowing user to pick any point on the forward curve.
Feed Name: interest.rate
Method: subscribe
Request:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [{
"frequency": "1000ms",
"batch": [{
"sid": "ir_1",
"feed": "interest.rate",
"base_asset": "BTC",
"expiry": "2025-10-31T08:00:00Z"
}, {
"sid": "ir_2",
"feed": "interest.rate",
"base_asset": "ETH",
"expiry": "2025-12-26T08:00:00Z"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 7
}
}
}
]
}
Request Explanation:
jsonrpc
String
JSON-RPC protocol version. Must be "2.0".
method
String
Must be "subscribe".
params
Array
Array containing subscription configuration objects.
params.frequency
String
Max publishing rate. Eg., values: 1000ms, 20000ms.
params.batch
Array
Array of subscription parameter objects.
params.batch.sid
String
Unique identifier for this subscription item.
params.batch.feed
String
Feed type. Must be interest.rate.
params.batch.base_asset
String
The base asset (ie. BTC)
params.batch.expiry
ISO 8601 string
Expiry date/time.
Response (Subscription Confirmation):
{
"jsonrpc": "2.0",
"result": [{
"batch": {
"frequency": "1000ms",
"batch": [{
"sid": "ir_1",
"feed": "interest.rate",
"base_asset": "BTC",
"expiry": "2025-10-31T08:00:00Z"
}, {
"sid": "ir_2",
"feed": "interest.rate",
"base_asset": "ETH",
"expiry": "2025-12-26T08:00:00Z"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 7
}
}
}
}
]
}Response Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
result
Array
Array containing subscription confirmation objects.
result.batch
Array
Echo of the subscribed batch items.
Data Update Example:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [{
"data": {
"values": [{
"sid": "ir_1",
"v": 0.0223746
}, {
"sid": "ir_2",
"v": 0.0227152
}
],
"timestamp": 1762250026000
}
}
]
}Data Update Explanation:
jsonrpc
String
JSON-RPC protocol version. Always "2.0".
method
String
Always "subscription" for data updates.
params
Array
Array containing update data objects.
params.data
Object
Data object containing values and timestamp.
params.data.values
Array
Array of value objects, one per sid.
params.data.values.sid
String
Subscription identifier matching the request.
params.data.values.v
Float
The interest rate value.
params.data.timestamp
Integer
Timestamp when the data was recorded.
4.10 Unsubscribe
Description: Unsubscribe from a previously established subscription.
Method: unsubscribe
Request:
{
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": {
"client_id": "mark_subscription_1"
}
}Request Explanation:
jsonrpc
String
true
JSON-RPC protocol version. Must be "2.0".
method
String
true
Must be "unsubscribe".
params
Object
true
Parameters object containing unsubscription details.
params.client_id
String
true
The client_id of the subscription to unsubscribe from.
Response (Success):
{
"jsonrpc": "2.0",
"result": "ok"
}5. Error Handling
Error Messages
WebSocket API errors follow the standard JSON-RPC 2.0 error format.
Invalid API Key
-2610
{
"jsonrpc": "2.0",
"error": {
"message": "Invalid API Key",
"code": -2610
}
}Occurs when an invalid or missing API key is provided. Ensure that a valid api_key is included in the authentication request.
Invalid method
-2610
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -2610,
"message": "Invalid method"
}
}Triggered when an invalid method name is specified in the request.
Invalid Params
-2610
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -2610,
"message": "Invalid parameters: xxxx"
}
}Occurs when required parameters are missing or invalid in the request.
Invalid Request
-32600
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32600,
"message": "Invalid Request"
}
}The JSON sent is not a valid Request object.
6. Usage Example
Below is a complete example demonstrating authentication, subscription, receiving updates, and unsubscribing.
Step 1: Authenticate
{
"jsonrpc": "2.0",
"id": 1,
"method": "authenticate",
"params": {
"api_key": "your_api_key_here"
}
}Step 2: Subscribe to Mark Price
{
"jsonrpc": "2.0",
"id": 2,
"method": "subscribe",
"params": [
{
"frequency": "1000ms",
"client_id": "my_subscription",
"batch": [
{
"sid": "btc_mark",
"feed": "mark.px",
"asset": "perpetual",
"base_asset": "BTC",
"quote_asset": "USD"
}
],
"options": {
"format": {
"timestamp": "ms",
"hexify": false,
"decimals": 2
}
}
}
]
}Step 3: Receive Updates
{
"jsonrpc": "2.0",
"method": "subscription",
"params": [
{
"data": {
"values": [
{ "sid": "btc_mark", "v": 111370.50 }
],
"timestamp": 1761811200000
}
}
]
}Step 4: Unsubscribe
{
"jsonrpc": "2.0",
"id": 3,
"method": "unsubscribe",
"params": {
"client_id": "my_subscription"
}
}7. Supported Base Assets
mark.px / index.px
To fetch all the allowed currencies for pricing feeds, please use the catalog API with the following request body to call the Catalog API
{
"fields": [],
"start": "2025-10-06T06:00:00Z", //Use current date
"end": "2025-10-06T06:00:00Z", //Use current date
"exchanges":["blockscholes"],
"asset_types":["option"], // "spot"|"perpetual"|"future"
"base_assets":[]
}*.iv / model.params
To fetch all the allowed currencies for IV feeds, please use the catalog API with the following request body to call the Catalog API
{
"fields": [],
"start": "2025-10-06T06:00:00Z", //Use current date
"end": "2025-10-06T06:00:00Z", //Use current date
"exchanges":["composite"],
"asset_types":["option"],
"base_assets":[]
}interest.rate
To fetch all the allowed currencies for interest rates, please use the catalog API with the following request body to call the Catalog API
{
"fields": [],
"start": "2025-10-06T06:00:00Z", //Use current date
"end": "2025-10-06T06:00:00Z", //Use current date
"exchanges":["blockscholes"],
"asset_types":["future"],
"base_assets":[]
}Last updated