# WebSocket API

The WebSocket API provides real-time streaming of easily-consumable data regarding all important aspects on the Demex L1 chain. This API is recommended for building most applications.

## Endpoints

These public WebSocket endpoints can be used to stream data from Demex.

**Mainnet:** `wss://ws-api.carbon.network/ws`

**Testnet:** `wss://test-ws-api.carbon.network/ws`

{% hint style="warning" %}
It is important to note that the above public endpoints do not have any guarantees on uptime and may not always be accessible, even when the blockchain may operating normally. 
{% endhint %}

{% hint style="success" %}
To ensure maximum reliability, it is advisable to [run your own node](/technical/running-a-node.md) with WebSockets enabled.
{% endhint %}

## Documentation

While interacting with the WebSocket API is straightforward, detailed documentation for each individual endpoint is still underway. 

In the meantime, you may already begin using it in production via the following quickstart guide.

### Streaming Subscriptions

To subscribe to a specific subscription, you should use the `subscribe` method while specifying the `channel` you wish to stream.

#### **Request Format**

* **request\_id:** This serves as an identifier to distinguish between different subscription requests. The subscription response will include this identifier.
* **method:** This refers to the name of the method, which is either `subscribe` or `unsubscribe`.
* **params:** This refers to the request parameters, which is consists of the `channels` object. It is an array of the required channels for subscription, postfixed by the respective subscription parameters and delimited by a colon (`:`). You can find the list of supported channels [here](https://github.com/Switcheo/carbon-js-sdk/blob/6e8a0f523707a1a76ef35cdad482d55c9b9b65ee/src/websocket/types.ts#L1) and the required parameters [here](https://github.com/Switcheo/carbon-js-sdk/blob/6e8a0f523707a1a76ef35cdad482d55c9b9b65ee/src/websocket/types.ts#L85).

#### Response Format

The successful response will echo the subscribed channel and the request ID.

#### Subscription Feed

* **block\_height:** This is the block height of the data
* **channel:** This is the subscription's channel
* **result:** This field contains the data. You can find the data structure of stream updates from subscriptions [here](https://github.com/Switcheo/carbon-js-sdk/blob/master/src/websocket/models.ts).
* **update\_type:** This field specifies the type of the accompanying data and may be one of: `full_state | delta` .
  * If the value of this field is `full_state`, it indicates that the accompanying data represents a full view of the data you intend to stream. This update type is always sent immediately after a new channel subscription, and serves as a foundation for future updates - clients should maintain the given data and modify it based on future updates. 
  * If the value of this field is `delta`, it means that the accompanying data only contains deltas (modifications) that should be applied on the full state that the client is maintaining.

**Subscription Feed**

* **block\_height:** This is the block height of the data
* **channel:** This is the subscription's channel
* **result:** This field contains the data. You can find the data structure of stream updates from subscriptions [here](https://github.com/Switcheo/carbon-js-sdk/blob/master/src/websocket/models.ts).
* **update\_type:** This field specifies the type of the accompanying data and may be one of: `full_state | delta` .
  * If the value of this field is `full_state`, it indicates that the accompanying data represents a full view of the data you intend to stream. This update type is always sent immediately after a new channel subscription, and serves as a foundation for future updates - clients should maintain the given data and modify it based on future updates.
  * If the value of this field is `delta`, it means that the accompanying data only contains deltas (modifications) that should be applied on the full state that the client is maintaining.

**Example**

Let's stream orders for the account `swth12j2frlmwc26xv9dqj08tnqxpjy7yklsxa8p4da` in the `swth_eth` market.

```json
// Request body
{
    "id": "request-42", // Request ID
    "method": "subscribe",
    "params": {
        "channels": ["orders_by_market:swth_eth:swth12j2frlmwc26xv9dqj08tnqxpjy7yklsxa8p4da"] 
        // `orders_by_market` is the channel name, `:` is the delimiter, 
        // followed by the market and address parameters, also delimited by `:`.
    }
}

// Response body
{
    "id": "request-42"
    "result": ["orders_by_market:swth_eth:swth12j2frlmwc26xv9dqj08tnqxpjy7yklsxa8p4da"]
}

// Subscription feed (result is specific to the subscribed channel)
{
    "block_height": 3074
    "channel": "orders_by_market:swth_eth:swth12j2frlmwc26xv9dqj08tnqxpjy7yklsxa8p4da"
    "result": [
        {
            market: "swth_eth", 
            side: "buy",
            …
        },
        …
    ],
    "update_type": "full_state"
}
{
    "block_height": 3074
    "channel": "balances:swth12j2frlmwc26xv9dqj08tnqxpjy7yklsxa8p4da"
    "result": [
        {
            "available": "700000000",
            "order": "0",
            "position": "0",
            "denom": "swth"
        },
        …
    ],
    "update_type": "delta"
}
```


---

# Agent Instructions: 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:

```
GET https://guide.dem.exchange/technical/websocket-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.