Carbon WebSocket

The Carbon WebSocket provides real-time streaming of easily-consumable data on the Carbon blockchain in real-time. This API is recommended for building most applications.

Endpoints

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

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

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

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.

To ensure maximum reliability, it is advisable to run your own node with WebSockets enabled.

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 and the required parameters here.

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.

• 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.

• 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.

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