Websocket API
This document describes version 4 of the websocket API. Any earlier version is unsupported and may be withdrawn at any time.
Base URL
Default:
wss://www.cfbenchmarks.com/ws/v4
Nasdaq Indices
wss://nciprod1.cfbenchmarks.com/ws/v4
Authorization
This API requires users to specify an API key. This key can be obtained by contacting CF Benchmarks for a license.
If connecting using Javascript, assuming the key username is 'abc' and the key password is '123', you would connect by specifying the protocol as the array ['cfb', 'abc, '123]
.
Some language APIs require the key to be specified in the websocket request header. In this case you would provide the username and key in the request header with a header field of the form Authorization: Basic <credentials>
where credentials is the Base64 encoding of username and key joined by a single colon ':'.
Commands
Info
The Info endpoint returns details of all streams an API key provides access to.
Example:
{ "type":"info" }
Response:
{
"type": "info",
"streams": [
{
"id": "ETHUSD_RTI"
},
{
"id": "BRTI"
},
{
"id": "ETHUSD_RR"
},
{
"id": "BRR"
}
]
}
Subscribe
Field | Type | Description | Expected value |
---|---|---|---|
type |
string | Command | subscribe |
id |
string | Stream ID | One of the stream IDs above |
stream |
string | Stream type | One of: [value ,constituents ] |
Example:
{ "type": "subscribe", "id": "BRTI", "stream": "value" }
Note that the constituents
streamtype is restricted to the NCIS and NCI indices, and is permissioned on an individual basis. Please contact CF Benchmarks if you require access.
Response:
No direct response if successful. The most recent value will be sent, and subsequent values until the unsubscribe command is sent.
Errors are described below.
Unsubscribe
Field | Type | Description | Expected value |
---|---|---|---|
type |
string | Command | unsubscribe |
id |
string | Stream ID | One of the stream IDs above |
stream |
string | Stream type | One of: [value ,constituents ] |
Example:
{ "type": "unsubscribe", "id": "BRTI", "stream": "value" }
Response:
No direct response if successful. Messages for the subscription will cease.
Errors are described below.
Messages
Value
Field | Type | Description | Expected value |
---|---|---|---|
type |
string | Message type | value |
id |
string | Stream ID | One of the stream IDs above |
time |
integer | Calculation time of value in milliseconds since Unix epoch | |
value |
number | Stream value |
Example:
{ "type": "value", "id": "BRTI", "value": "8835.56", "time": 1579264280000 }
In addition to the above, each value
message may contain any of the following fields:
Field | Type | Description | Expected value |
---|---|---|---|
amendTime |
(Optional) integer | If the value has been amended after being previously published, this field indicates the time of the amendment in milliseconds since Unix epoch. If no amendment has been made, the field will not be present. | |
repeatOfPreviousValue |
(Optional) boolean | If an error has occurred during calculation such that an index value could not be calculated for that day, and it has been replaced with the value from the previous day, this boolean field will exist, and will be true . If no such error has occurred, the field will not be present. |
Example:
{ "type": "value", "id": "BRR", "value": "57260.71", "time": 1620313200000, "amendTime": 1620313300000, "repeatOfPreviousValue": true }
Constituents
Field | Type | Description | Expected value |
---|---|---|---|
type |
string | Message type | constituents |
id |
string | Stream ID | One of the stream IDs above |
time |
integer | Calculation time of value in milliseconds since Unix epoch | |
value |
number | Index value | |
divisor |
number | Index divisor | |
constituents |
object | Object containing constituent name, value, weight and exchange weights |
Example:
{
"type":"constituents",
"time":1618922805000,
"id":"NCI",
"value": "2835.55",
"divisor": "203484212.3109",
"constituents":[
{"constituent": "LINK", "value": "35.0013", "weightPercent": "1.27",
"exchanges": [
{"exchange": "exchangeA", "weightPercent": "54.14"},
{"exchange": "exchangeB", "weightPercent": "20.55"},
{"exchange": "exchangeC", "weightPercent": "25.31"}
]
},
{"constituent": "BCH", "value": "793.3554", "weightPercent": "1.03",
"exchanges": [
{"exchange": "exchangeA", "weightPercent": "59.38"},
{"exchange": "exchangeB", "weightPercent": "20.62"},
{"exchange": "exchangeC", "weightPercent": "20.00"}
]
},
{"constituent": "ETH", "value": "2454.7451", "weightPercent": "16.86",
"exchanges": [
{"exchange": "exchangeA", "weightPercent": "70.43"},
{"exchange": "exchangeB", "weightPercent": "19.33"},
{"exchange": "exchangeC", "weightPercent": "10.24"}
]
},
{"constituent": "XLM", "value": "0.4516", "weightPercent": "0.65",
"exchanges": [
{"exchange": "exchangeA", "weightPercent": "40.31"},
{"exchange": "exchangeB", "weightPercent": "30.45"},
{"exchange": "exchangeC", "weightPercent": "29.24"}
]
},
{"constituent": "XBT", "value": "52435.7103", "weightPercent": "78.61",
"exchanges": [
{"exchange": "exchangeA", "weightPercent": "9.26"},
{"exchange": "exchangeB", "weightPercent": "50.32"},
{"exchange": "exchangeC", "weightPercent": "40.42"}
]
},
{"constituent": "LTC", "value": "214.3741", "weightPercent": "1.58",
"exchanges": [
{"exchange": "exchangeA", "weightPercent": "20.40"},
{"exchange": "exchangeB", "weightPercent": "39.18"},
{"exchange": "exchangeC", "weightPercent": "40.42"}
]
}
]
}
In addition to the above, each constituents
message may contain any of the following fields:
Field | Type | Description | Expected value |
---|---|---|---|
amendTime |
(Optional) integer | If the value has been amended after being previously published, this field indicates the time of the amendment in milliseconds since Unix epoch. If no amendment has been made, the field will not be present. | |
repeatOfPreviousValue |
(Optional) boolean | If an error has occurred during calculation such that an index value could not be calculated for that day, and it has been replaced with the value from the previous day, this boolean field will exist, and will be true . If no such error has occurred, the field will not be present. |
Command Errors
Any command that results in an error returns the command with a success flag and a reason for the error.
Field | Type | Description | Expected value |
---|---|---|---|
type |
string | Command | unsubscribe |
id |
string | Stream ID | One of the stream IDs above |
stream |
string | Stream type | One of: [value ] |
success |
boolean | Was the command successful | |
reason |
string | Reason for the error |
Example:
{ "type": "foo", "id": "BRTI", "stream": "value", "success": false, "reason": "Unrecognised command" }