Message Types

The WebSocket API comprises to sets of messages, those that are sent by ypu (the WebSocket client) are called 'client-side messages' and those sent by Gravitan (the WebSocket server) are called 'server-side messages'.

All messages include a json attribute called message_type that represents the type of the message and determines the other attributes that may be present or required in the json.

Client-Side Message Types:

subscribe

The subscribe message is used to initiate a new WebSocket subscription. The message allows subscribing to any number of 'prediction services'.

As an example, the following message allows you to start receiving price movement predictions for CME futures market covering the E-mini S&P 500 contract expiring in September 2023 and also ETHUSDT in Binance spot market.

Sending prediction_params parameter along with prediction type allows you to specify which variation of a prediction type you need when multiple variations are available.

If prediction_params is not specified, we use a set of defaults that is usually the service that is used most frequently.

{
  "message_type": "subscribe",
  "predictions": [
    {
      "type": "price_movement",
      "exchange_id": "cme",
      "symbol": "ESU3",
      "params": {
        "threshold": "0.00002",
        "horizon": "10"
      }
    },
    {
      "type": "price_movement",
      "exchange_id": "binance",
      "symbol": "ETHUSDT"
    }
  ],
  "heartbeat": True,
  "timestamp": 1689110444102,
  "api_key": "replace with your API key"
  "signature": "replace with the actual signature"
}

Upon subscribing, a single heartbeat message is sent by the server as a confirmation of the current subscriptions.

add_subscription

This message type is used to add new subscriptions to an existing WebSocket connection.

The message attributes are identical to subscribe message with the exception of the message_type .

Prior to using add_subscription, you will need an existing subscription. Make sure to send a valid subscription message at least once before attempting to update it.

remove_subscription

This message type is used to remove any subscriptions

The message attributes are identical to subscribe message with the exception of the message_type .

Prior to using remove_subscription, you will need an existing subscription. Make sure to send a valid subscription message at least once before attempting to update it.

get_subscriptions

This message type is used to retrieve all the current subscriptions for your existing WebSocket connection.

Sample response for `get_subscriptions` message

{
    "message_type":"subscriptions",
    "predictions":[
        {
            "exchange_id":"binance_futures",
            "symbol":"BTCUSDT",
            "type": "price_movement",
            "params":{"threshold":"0.00002","horizon":10}
            }
        ],
    "heartbeat":true
}

Server-Side Message Types

Server messages are sent from the Gravitan's WebSocket data feed.

subscriptions

This message is sent from the server and represents a summary of your existing subscriptions. The message is sent upon creating a new subscription or changing it. The message is identical to get_subscriptions

Sample subscriptions message

{
    "message_type":"subscriptions",
    "predictions":[
        {
            "exchange_id":"dydx",
            "symbol":"BTC-USD",
            "type":"price_movement",
            "params":{"threshold":"0.00002","horizon":10}
        }
    ],
    "heartbeat":true
}

heartbeat

When subscribing to heartbeat event then the server will send you a small message every 10 seconds. This is useful to make sure the connection remains alive even though if the server does not send messages for some time hence preventing the connection to be terminated by some network providers (e.g. CloudFlare).

error

In case of errors, a message type of error is published.

• Authentication error

• Invalid input error

• Internal server error

• Throttle error

Here is a sample error message sent from the server when the subscribe method provides invalid prediction detail.

{ 
    "message_type": "error", 
    "code": 3, 
    "message": "invalid subscription details" 
}

price_movement

Here is a sample price movement message:

{
    "message_type":"price_movement",
    "sequence":1689729341282000,
    "timestamp":"2023-07-19T01:15:41.264972Z",
    "exchange_id":"cme",
    "symbol":"ESU3",
    "direction":-1,
    "threshold":"0.00002",
    "horizon":10
}