Websocket Server Documentation

Subscribing to channels

There are several channels that you can subscribe to. Each channel represents a different type of event that you can listen to.

To subscribe to a channel, you need to send a subscribe message to the websocket server, after you establish a connection to our websocket server. Below is an example of how to subscribe to the prices channel.

Copy
Copied
{
  "action": "subscribe",
  "channel": "prices-v1",
  "payload": [
    {
      "type": "cr",
      "asset": "BTC",
      "fiat": "EUR"
    },
    {
      "type": "s",
      "asset": "AAPL",
      "fiat": "EUR"
    }
  ]
}

Where:

  • action is the action that you wants to perform. Supported actions are: subscribe or unsubscribe .
  • channel is the channel that you want to subscribe to. You can subscribe to multiple channels on the same connection, or you can open multiple connections to subscribe to different channels.
  • payload is an array of objects containing the following fields:
    • type is the type of the asset. It can be cr for crypto, s for securities, f for fiat, i for index, co for commodity, es for equity_security.
    • asset is the asset symbol.
    • fiat is the fiat symbol
    • The value can be missing and in that case it is assumed that you want to subscribe to all asset-fiat pairs.
    • You can only subscribe to assets that are associated with your domain.
    • The payload can also be of the form {"fiat": "EUR"} which would indicate subscription to all assets against the indicated fiat.
    • Take into account that you cannot mix subscription types. On the same subscription action, you can only subscribe to one of:
      • an asset list
      • all assets against a specific fiat or more than one fiat.
      • all assets against all fiats.

The above rules apply for both channels that are available for subscription.

Examples

Subscribe to a list of assets

Copy
Copied
{
  "action": "subscribe",
  "channel": "prices-v1",
  "payload": [
    {
      "type": "cr",
      "asset": "BTC",
      "fiat": "EUR"
    },
    {
      "type": "s",
      "asset": "AAPL",
      "fiat": "EUR"
    }
  ]
}

Subscribe to all assets against a specific fiat

Copy
Copied
{
  "action": "subscribe",
  "channel": "prices-v1",
  "payload": [
    {
      "fiat": "EUR"
    }
  ]
}

Subscribe to all assets against multiple fiats

Copy
Copied
{
  "action": "subscribe",
  "channel": "prices-v1",
  "payload": [
    {
      "fiat": "EUR"
    },
    {
      "fiat": "USD"
    }
  ]
}

Subscribe to all assets against all fiats

Copy
Copied
{
  "action": "subscribe",
  "channel": "prices-v1"
}

Success messages

For each action taken, if the action was successful, you will receive a success message from the server.

Here is an example of a success message:

Copy
Copied
{
    "action": "subscribe",
    "channel": "prices-v1",
    "status": "success"
}

Error messages

If there is an error in the subscription message, you will receive an error message from the server.

Here are some examples of error messages:

Invalid channel

Copy
Copied
{
  "action": "subscribe",
  "channel": "non-existent-channel",
  "error": "channel not supported"
}

Invalid fiat

Copy
Copied
{
  "action": "subscribe",
  "channel": "price-changes-v1",
  "error": "fiat not found: XXX"
}

Where XXX is the symbol of the fiat that you tried to subscribe to and is not supported.

Asset not found for domain

Copy
Copied
{
  "action": "subscribe",
  "channel": "price-changes-v1",
  "error": "asset not found for domain: ABC"
}

Where ABC is the symbol of the asset that you tried to subscribe to and is not associated with your domain.

Supported Channels

The following channels are available for subscription:

  • prices-v1 : This channel provides real-time price updates for assets. Each asset-fiat pair receives an update roughly every 15 seconds.
  • price-changes-v1 : This channel provides real-time price changes for assets.

Price Updates

Below is an example of a message that you will receive when you subscribe to the prices-v1 channel.

Copy
Copied
{
  "AP":"65544.85350",
  "BP":"65217.84675",
  "U": 1706521791,
  "T": "cr",
  "A": "BTC",
  "F": "EUR",
  "CH": "prices-v1"
}

Where:

  • AP is the ask price
  • BP is the bid price
  • U is the unix timestamp of the update
  • T is the type of the asset. It can be cr for crypto, s for securities, f for fiat, i for index, co for commodity, es for equity_security.
  • A is the asset symbol
  • F is the fiat symbol
  • CH is the channel

Price Changes

Below is an example of a message that you will receive when you subscribe to the price-changes-v1 channel.

Copy
Copied
{
  "T": "cr",
  "A": "BTC",
  "F": "EUR",
  "CH": "price-changes-v1",
  "D": "-1.5133276010318143",
  "I": "1.273209549071618",
  "W": "-1.8677176148046607",
  "M": "0.297723292469352",
  "6M": "-7.9408455232277769",
  "Y": "-24.3261099365750529",
  "5Y": "-26.7534660050135571",
  "DV": "-0.88",
  "IV": "0.72",
  "WV": "-1.09",
  "MV": "0.17",
  "6MV": "-4.94",
  "YV": "-18.41",
  "5YV": "-20.918",
  "MVOL": "0.1185439986130654"
}

Where:

  • T is the type of the asset. It can be cr for crypto, s for securities, f for fiat, i for index, co for commodity, es for equity_security.
  • A is the asset symbol
  • F is the fiat symbol
  • CH is the channel
  • D is the daily change in %
  • I is the intraday change in %
  • W is the weekly change in %
  • M is the monthly change in %
  • 6M is the 6 month change in %
  • Y is the yearly change in %
  • 5Y is the 5 year change in %
  • DV is the daily change in value
  • IV is the intraday change in value
  • WV is the weekly change in value
  • MV is the monthly change in value
  • 6MV is the 6 month change in value
  • YV is the yearly change in value
  • 5YV is the 5 year change in value
  • MVOL is the monthly volatility

Be advised that price changes are available only for EUR for now. Subscription to other fiats will work, but you will not receive any messages for those fiats.

Unsubscribing from channels

To unsubscribe from a channel, you need to send an unsubscribe message to the websocket server. Below is an example of how to unsubscribe from the prices channel.

Copy
Copied
{
  "action": "unsubscribe",
  "channel": "prices-v1"
}

You cannot unsubscribe selectively from assets. You can only unsubscribe from the entire channel.

Ping/Pong

Our websocket server supports ping/pong messages, in accordance with RFC 6455.

If the connection is idle for one minute or more, the server will close the connection. In order to avoid this, you need to send a ping message to the server at least once per minute. The server will respond with a pong message.

Supported fiats and assets

Fiats: Price changes are available only for EUR for now. Subscription to other fiats will work, but you will not receive any messages for those fiats. Assets: You can only subscribe to assets that are associated with your domain.