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

Upcoming Changes (30th July)

As described in this consultation, from July 30th CF Benchmarks will be adding support for amendments to previously published index values.

This will result in the following high-level changes:

• Index values may be delayed in exceptional circumstances.
• Index values may be amended after publication in exceptional circumstances.
• Index values may be replaced with the value from the previous day in exceptional circumstances.
• Amendments to previously published values will have an additional amendTime indicating the time of the most recent amendment of that value.
• Any value replaced with the previous day's value will have an additional repeatOfPreviousValue flag indicating the fact.
• Messages may be delivered out of order or repeated, for example if an amendment to a previously published value has occurred.
• Additional fields may be added to API messages in the future.

Please see below for details of the upcoming changes.

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 }

Upcoming Changes (30th July)

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

Upcoming Changes (30th July)

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