> For the complete documentation index, see [llms.txt](https://docs.21x.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.21x.eu/websocket-api.md).

# Websocket API

This API provides websocket support for subscribing to trading data channels such as Ticker (Level 1), Orderbook (Level 2), Orders (Level 3), and Trades (User).
\
21x WebSocket API allows a client to subscribe and receive events in near real-time.

### Connection life cycle

* Establish Connection: The client connects to the WebSocket endpoint. If there's a network error, retry with a jittered exponential backoff.
* Initialize: After connecting, the client sends an init message to start communication.
* Acknowledge: The client waits for an acknowledgment message that includes a timeout value for periodic keep-alive (ka) messages.
* Monitor Keep-Alive: The client tracks incoming ka messages. If none are received within the specified timeout, the client closes the connection.
* Subscribe: The client sends a subscribe message to register interest in specific events. Multiple subscriptions are supported per connection.
* Confirm Subscription: The client waits for confirmation messages indicating successful subscriptions.
* Listen for Events: The client receives and processes events as they are published.
* Unsubscribe: The client sends an unsubscribe message to stop receiving events for a subscription.
* Disconnect: Once all subscriptions are unregistered and no messages are pending, the client closes the WebSocket connection.

### WebSocket API Message

All messages are sent and published using `application/json` content type.

**Common fields in the messages**

#### `id`

* **Description**: The client-provided ID of the operation. This property is required and is used to correlate response error and success messages.
* **Requirements**: For subscriptions, this property must be unique for all subscriptions within a connection.
* **Format**: A string limited to a maximum of 128 alphanumeric + special character (\_,+,-) characters.
* **Regex**: `/^[a-zA-Z0-9-_+]{1,128}$/`

#### `type`

* **Description**: The type of operation being performed.
* **Supported Operations**: `subscribe`, `unsubscribe`, `publish`.
* **Details**: Must be one of the message types defined in the "Configuring message details" section.

#### `channel`

* **Description**: The channel to subscribe to events.
* **Format**: A string made up of one to five segments separated by a slash.
  * Each segment is limited to 50 alphanumeric + dash characters.
  * Case sensitive.
* **Examples**: `channelNamespaceName`, `channelNamespaceName/sub-segment-1/subSegment-2`
* **Regex**: `/^\/?[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?(?:\/[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?){0,4}\/?$/`

#### `authorization`

* **Description**: The authorization headers necessary to authorize the operation.
* **Examples**:
  * **ApiKey**: Contains both `host` and `x-api-key`.
  * **IAM**: Contains `host`, `x-amz-date`, `x-amz-security-token`, and `authorization`.

### Channels

Channels allow clients to select and filter the information of interest.
\
When subscribing to a given channel wildcard suffix (`*`) can be used to subscribe to all subchannels.

**Example:**
`/orders/*` will subscribe the client for notification for all active markets
`/order/bytradingpair/ABCXYZ` will subscribe client only for notifications for market ABCXYZ

**Caution:**
\
Subscribing for a non-existing market will not result in error. The subscription will be valid however, no data will be available.

***

### Message Details

#### Connection Init Message

* **Description**: After the client establishes the WebSocket connection, the client sends an `init` message to initiate the connection session.

```json
{
  "type": "connection_init"
}
```

#### Connection Acknowledge Message

* **Description**: AWS AppSync responds with an `ack` message containing a connection timeout value.
* **Notes**: If the client doesn’t receive a keep-alive message within the connection timeout period (5 minutes), the client should close the connection.

```json
{
  "type": "connection_ack",
  "connectionTimeoutMs": 300000
}
```

#### Keep-Alive Message

* **Description**: API periodically sends a keep-alive message to maintain the connection.
* **Interval**: 60 seconds.
* **Notes**: Clients do not need to acknowledge these messages.

```json
{
  "type": "ka"
}
```

#### Subscribe Message

* **Description**: After receiving a `connection_ack` message, the client can send a subscription registration message to listen for events on a channel.
* **Properties**:
  * `id`: The unique ID of the subscription per client connection.
  * `channel`: The channel to which the subscribed client is listening.
  * `authorization`: An object containing the fields required for authorization.

```json
{
  "type": "subscribe",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69",
  "channel": "/namespace/subB/subC",
  "authorization": {
    "x-api-key": "da2-12345678901234567890123456",
    "host": "example1234567890000.appsync-api.us-east-1.amazonaws.com"
  }
}
```

#### Subscription Acknowledgment Message

* **Description**: Subscription operation acknowledges with a success message.
* **Properties**:
  * `id`: The ID of the corresponding subscribe operation that succeeded.

```json
{
  "type": "subscribe_success",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69"
}
```

#### Subscription Error Message

* **Description**: Subscription operation error message.

```json
{
  "type": "subscribe_error",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69",
  "errors": [
    {
      "errorType": "SubscriptionProcessingError",
      "message": "There was an error processing the operation"
    }
  ]
}
```

#### Data Frame Message

* **Description**: When an event is published to a channel the client is subscribed to, the event is delivered in a data message.
* **Properties**:
  * `id`: The ID of the corresponding subscription for the channel.
  * `event`: The JSON array of stringigifed JSON event objects, each object representing a separate data item

```json
{
  "type": "data",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69",
  "event": ["\"...JSON data content...\""]
}
```

* **Error Case**:

```json
{
  "type": "broadcast_error",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69",
  "errors": [
    {
      "errorType": "MessageProcessingError",
      "message": "There was an error processing the message"
    }
  ]
}
```

#### Unsubscribe Message

* **Description**: When the client wants to stop listening to a subscribed channel, the client sends an `unsubscribe` message.
* **Properties**:
  * `id`: The ID of the corresponding subscription.

```json
{
  "type": "unsubscribe",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69"
}
```

#### Unsubscribe Acknowledgment Message

* **Description**: Unsubscribe operation acknowledges with a success message.
* **Properties**:
  * `id`: The ID of the corresponding unsubscribe operation that succeeded.

```json
{
  "type": "unsubscribe_success",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69"
}
```

#### Unsubscribe Error Message

* **Description**: Unsubscribe operation error message.

```json
{
  "type": "unsubscribe_error",
  "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69",
  "errors": [
    {
      "errorType": "UnknownOperationError",
      "message": "Unknown operation id ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69"
    }
  ]
}
```

#### Disconnecting the WebSocket

* **Description**: Before disconnecting the WebSocket, the client should ensure that no operations are in progress.
* **Recommendations**:
  * Unregister all subscriptions before disconnecting to avoid data loss.

***

### Error handling

**Connection lost**
\
Client must detect situation that connection is lost / dropped and reconnect to the server.
\
Data frame messages will not be retransmitted.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.21x.eu/websocket-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.