Website Github APIs Join Research & Development

Websocket API

Subscribe to live-streamed market events

Overview

The websocket API streams market updates at low latency for use cases that require monitoring of the market in real time. It supports all feeds, symbols, and exchanges for L3 Atom. Messages will be of the form:

{
    "feed": <Name of the feed>,
    "exchange": <Exchange the message is from>,
    "symbol": <What symbol the message is for>,
    "data": [
        ...
    ]
}

in cases where you specify the feed, exchange, and symbol in the subscription message. In other types of feeds, you will see a similar structure, but you may not see an exchange or symbol field if it is not relevant. data is an array of the market updates / events, whose format is dependent on the feed. However, each entry in data will have one of the following structures:

{
    ...,
    "event_timestamp": "2022-11-10T02:46:35.255000Z",
    "atom_timestamp": 1668048395421519
}
{
    ...,
    "blockTimestamp": "2022-11-10T02:46:35Z",
    "atomTimestamp": 1668048395421519
}

Where the former relates to off-chain data with individual event timestamps, and the latter relates to on-chain data with timestamps of blocks. These formats are guaranteed throughout all feeds.

See the Schema Reference for more information on what all of these fields mean. Note that when sending out floats or large integers, we encode them as strings. This is because JSON can't guarantee floating point precision if these numbers were simply encoded and sent out as floats, but by sending them out as strings, we can preserve precision regardless. This is a practice that's commonly used by other Websocket APIs.

Base Endpoint

wss://ws.shared.projectx.network

Quickstart

The following code shows an example of how you can interact with this API:

websocket_test.py
import sys
import websockets
import asyncio
import json

#connects to endpoint ENDPOINT
async def main():
    ENDPOINT = 'wss://ws.shared.projectx.network'
    async with websockets.connect(ENDPOINT) as websocket:
        await websocket.send('{"action": "subscribe", "exchange": "%s", "channel": "%s", "symbol": "%s"}' % (sys.argv[1], sys.argv[2], sys.argv[3]))
        async for message in websocket:
            msg = json.loads(message)
            print(json.dumps(msg, indent=4, default=str))

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nExiting...")

Install the async websockets library if you don't have it already:

pip install websockets

and then run by passing in command line arguments for what exchange, feed, and symbol to subscribe to. Below is an example.

python websocket_test.py coinbase trades_l3 BTC.USD

Off-Chain

L3 Lob Events

Every update to the orderbook, including order IDs. Can be used to rebuild the exchange's orderbook.

Schema

L3 Lob

Subscribe

{"action": "subscribe", "exchange": "coinbase", "channel": "lob_l3", "symbol": "BTC.USD"}

Unsubscribe

{"action": "unsubscribe", "exchange": "coinbase", "channel": "lob_l3", "symbol": "BTC.USD"}

Initial Response

{
    "message": "Subscribed to coinbase_lob_l3_BTC.USD"
}

Example message

{
    "feed": "lob_l3",
    "exchange": "coinbase",
    "symbol": "BTC.USD",
    "data": [
        {
            "price": "15838.64",
            "size": "0.01880732",
            "side": "sell",
            "order_id": "ea3d8d15-bcb6-4a15-83f3-5cc980f07c5f",
            "event_timestamp": "2022-11-09T21:45:29.761000Z",
            "atom_timestamp": 1668030329870450
        },
        {
            "price": "16158.68",
            "size": "0.64250376",
            "side": "sell",
            "order_id": "7942ec03-a306-418b-8e8b-604bb25c3efa",
            "event_timestamp": "2022-11-10T02:46:35.235000Z",
            "atom_timestamp": 1668048395398340
        }
    ]
}

L2 Lob Events

Every update to the orderbook, excluding order IDs. Can be used to rebuild the exchange's orderbook.

Schema

L2 Lob

Subscribe

{"action": "subscribe", "exchange": "bybit", "channel": "lob", "symbol": "BTC.USDT"}

Unsubscribe

{"action": "unsubscribe", "exchange": "bybit", "channel": "lob", "symbol": "BTC.USDT"}

Initial Response

{
    "message": "Subscribed to bybit_lob_BTC.USDT"
}

Example message

{
    "feed": "lob",
    "exchange": "bybit",
    "symbol": "BTC.USDT",
    "data": [
        {
            "price": "16402.5",
            "size": "0.366803",
            "side": "sell",
            "event_timestamp": "2022-11-10T04:25:46.138000Z",
            "atom_timestamp": 1668054346187523
        },
        {
            "price": "16403.5",
            "size": "1.561",
            "side": "sell",
            "event_timestamp": "2022-11-10T04:25:46.138000Z",
            "atom_timestamp": 1668054346187523
        }
    ]
}

L3 Trade Events

Matches that occur on the exchange. Includes IDs of the orders involved.

Schema

L3 Trades

Subscribe

{"action": "subscribe", "exchange": "coinbase", "channel": "trades_l3", "symbol": "BTC.USD"}

Unsubscribe

{"action": "unsubscribe", "exchange": "coinbase", "channel": "trades_l3", "symbol": "BTC.USD"}

Initial Response

{
    "message": "Subscribed to coinbase_trades_l3_BTC.USD"
}

Example message

{
    "feed": "trades_l3",
    "exchange": "coinbase",
    "symbol": "BTC.USD",
    "data": [
        {
            "price": "16230.73",
            "size": "0.00612836",
            "taker_side": "sell",
            "trade_id": "450434726",
            "maker_order_id": "5e8ef683-3ed8-4981-8452-bd9c01f1a202",
            "taker_order_id": "b03599f4-68e9-497c-8bac-8a19bbec15e5",
            "event_timestamp": "2022-11-10T04:31:32.970000Z",
            "atom_timestamp": 1668054693082871
        }
    ]
}

L2 Trade Events

Matches that occur on the exchange. Does not provide IDs of the orders involved.

Schema

L2 Trades

Subscribe

{"action": "subscribe", "exchange": "bybit", "channel": "trades", "symbol": "BTC.USDT"}

Unsubscribe

{"action": "unsubscribe", "exchange": "bybit", "channel": "trades", "symbol": "BTC.USDT"}

Initial Response

{
    "message": "Subscribed to bybit_trades_BTC.USDT"
}

Example message

{
    "feed": "trades",
    "exchange": "bybit",
    "symbol": "BTC.USDT",
    "data": [
        {
            "price": "16224.62",
            "size": "5.2e-05",
            "taker_side": "buy",
            "trade_id": "2290000000030235772",
            "event_timestamp": "2022-11-28T12:24:26.654000Z",
            "atom_timestamp": 1669638266707418
        },
        {
            "price": "16224.62",
            "size": "0.000256",
            "taker_side": "sell",
            "trade_id": "2290000000030235773",
            "event_timestamp": "2022-11-28T12:24:26.703000Z",
            "atom_timestamp": 1669638266755074
        }
    ]
}

Ticker

High level overview of the state of the order book.

Schema

Ticker

Subscribe

{"action": "subscribe", "exchange": "kraken", "channel": "ticker", "symbol": "ADA.USD"}

Unsubscribe

{"action": "unsubscribe", "exchange": "kraken", "channel": "ticker", "symbol": "ADA.USD"}

Initial Response

{
    "message": "Subscribed to kraken_ticker_ADA.USD"
}

Example message

{
    "feed": "ticker",
    "exchange": "kraken",
    "symbol": "ADA.USD",
    "data": [
        {
            "bid_price": "0.34222",
            "bid_size": "1000.0",
            "ask_price": "0.342271",
            "ask_size": "534.14311985",
            "event_timestamp": "2022-11-10T04:39:03.361000Z",
            "atom_timestamp": 1668055143361911
        }
    ]
}

Candle

Open High Low Close Volume (OHLCV) data at the highest frequency we can get.

Schema

Candle

Subscribe

{"action": "subscribe", "exchange": "bitfinex", "channel": "candle", "symbol": "BTC.USD"}

Unsubscribe

{"action": "unsubscribe", "exchange": "bitfinex", "channel": "candle", "symbol": "BTC.USD"}

Initial Response

{
    "message": "Subscribed to bitfinex_candle_BTC.USD"
}

Example message

{
    "feed": "candle",
    "exchange": "bitfinex",
    "symbol": "BTC.USD",
    "data": [
        {
            "start": "2022-11-10T04:55:00Z",
            "end": "2022-11-10T04:56:00Z",
            "interval": "1m",
            "trades": -1,
            "closed": false,
            "o": "16467.0",
            "h": "16483.0",
            "l": "16466.0",
            "c": "16483.0",
            "v": "1.07438478",
            "event_timestamp": "2022-11-10T04:55:531000Z",
            "atom_timestamp": 1668056210416727
        }
    ]
}

Funding Rate

Funding rate updates for futures exchanges.

Schema

Funding Rate

Subscribe

{"action": "subscribe", "exchange": "kraken-futures", "channel": "funding_rate", "symbol": "DOT.USD-PERP"}

Unsubscribe

{"action": "unsubscribe", "exchange": "kraken-futures", "channel": "funding_rate", "symbol": "DOT.USD-PERP"}

Initial Response

{
    "message": "Subscribed to kraken-futures_funding_rate_DOT.USD-PERP"
}

Example message

{
    "feed": "funding_rate",
    "exchange": "kraken-futures",
    "symbol": "DOT.USD-PERP",
    "data": [
        {
            "mark_price": "5.739",
            "funding_rate": "0.001915258622467362",
            "next_funding_time": "2022-11-10T06:00:00Z",
            "predicted_rate": "0.0019215793541875",
            "event_timestamp": "2022-11-10T05:06:35.726000Z",
            "atom_timestamp": 1668056795958649
        }
    ]
}

Open Interest

Open Interest updates for futures exchanges.

Schema

Open Interest

Subscribe

{"action": "subscribe", "exchange": "deribit", "channel": "open_interest", "symbol": "DOT.USDC-PERP"}

Unsubscribe

{"action": "unsubscribe", "exchange": "deribit", "channel": "open_interest", "symbol": "DOT.USDC-PERP"}

Initial Response

{
    "message": "Subscribed to deribit_open_interest_DOT.USDC-PERP"
}

Example message

{
    "feed": "open_interest",
    "exchange": "deribit",
    "symbol": "DOT.USDC-PERP",
    "data": [
        {
            "open_interest": "15026.0",
            "event_timestamp": "2022-11-10T05:07:42.570000Z",
            "atom_timestamp": 1668056862863834
        }
    ]
}

On-Chain

Since each DEX supports a large number of symbol pairs and trades are far more infrequent than off-chain data, for now you must subscribe to exchanges as a whole and receive swaps data for all supported symbol pairs.

Ethereum Blocks

Details on every new block that is minted on the Ethereum mainnet.

Schema

Ethereum Blocks

Subscribe

{"action": "subscribe", "channel": "ethereum_blocks"}

Unsubscribe

{"action": "unsubscribe", "channel": "ethereum_blocks"}

Initial Response

{
    "message": "Subscribed to ethereum_blocks"
}

Example message

{
    "feed": "ethereum_blocks",
    "data": [
        {
            "atomTimestamp": 1671628718723934,
            "number": 16233325,
            "hash": "0x116b1455f30ef08d694d762989e39ff54d600fa7a8d0df8463265c856b0bec5f",
            "parentHash": "0xa1413c7e2210fa10a049f281a899bfc5b201dd8a1e422720b24b33b1a969c334",
            "nonce": "0x0000000000000000",
            "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
            "logsBloom": "0x6ea201c15748839044e0141382c2342184170e0002d06a844c49849a7621e51045c173184c4812814620182b0cd001741a232448be202f0b722bc76614ea2210102cc1345814044a7a0e8088b3130364a07425911370061008810b3d9c0021287a2003308606970520f192226a0e9f2f0a2cc8e3899caf450990151aca4a69a45205c280806add57896b6040636170d10c438101a1a2e06c00c86052151911e09e0331470e06680c020411822208a241407944102d30d00a0872a900120854500425009644480650013fe9010417201a254d0247b3ea085099cc19420880a10940942c4820084a0186ec352891d85c22e8713089a6ea8c50490c181096315c21",
            "transactionsRoot": "0xa0017f858ebe2c82559061af7d718233821edd985979a17d6eeabded550e80a5",
            "stateRoot": "0x74f63788ce3e85172e8a316bbea6d7e58332307c8a1df1dfc79589d7ffbdf14e",
            "receiptsRoot": "0x4e71a7d59e861f2eee172fef0a3b87b57f6df06f1ff1489566c18d223705ab2b",
            "miner": "0xdafea492d9c6733ae3d56b7ed1adb60692c98bc5",
            "difficulty": 0,
            "totalDifficulty": "58750003716598355984384",
            "extraData": "0x496c6c756d696e61746520446d6f63726174697a6520447374726962757465",
            "size": 55468,
            "gasLimit": "30000000",
            "gasUsed": "10281970",
            "blockTimestamp": "2022-12-21T13:18:35Z"
        }
    ]
}

Ethereum Transactions

Details on every transaction on the Ethereum mainnnet.

Ethereum Transactions aren't necessarily sent in the order they appear in the block, however a previous block's transactions will always come before a later block's transactions

Schema

Ethereum Transactions

Subscribe

{"action": "subscribe", "channel": "ethereum_transactions"}

Unsubscribe

{"action": "unsubscribe", "channel": "ethereum_transactions"}

Initial Response

{
    "message": "Subscribed to ethereum_transactions"
}

Example message

{
    "feed": "ethereum_transactions",
    "data": [
        {
            "atomTimestamp": 1671628791401843,
            "blockTimestamp": "2022-12-21T13:19:47Z",
            "hash": "0x37adcf8de530409a713782601320f7b72560087da5257563781c4a262131b5f0",
            "nonce": "0x37",
            "blockHash": "0xd84f2f5296b81215c817885b897883825ade4382c8678a873c5d588366b40f66",
            "blockNumber": 16233331,
            "transactionIndex": 172,
            "fromAddr": "0x4e591bed2b8d93c6f653167e3f6c0c19c594d42a",
            "toAddr": "0x974caa59e49682cda0ad2bbe82983419a2ecc400",
            "value": "74854507046267000",
            "gas": 21000,
            "gasPrice": 14914985079,
            "input": "0x",
            "maxFeePerGas": null,
            "maxPriorityFeePerGas": null,
            "type": "Legacy"
        },
        {
            "atomTimestamp": 1671628791401843,
            "blockTimestamp": "2022-12-21T13:19:47Z",
            "hash": "0x8da3009dbecb3b1eda1848bb90805abd261a6fc3d1347357eff7c8faef470e7b",
            "nonce": "0x0",
            "blockHash": "0xd84f2f5296b81215c817885b897883825ade4382c8678a873c5d588366b40f66",
            "blockNumber": 16233331,
            "transactionIndex": 192,
            "fromAddr": "0x00a79530c59737f2e1f1613d25796f2b8485b5ae",
            "toAddr": "0x974caa59e49682cda0ad2bbe82983419a2ecc400",
            "value": "74271675313341000",
            "gas": 21000,
            "gasPrice": 14914985079,
            "input": "0x",
            "maxFeePerGas": null,
            "maxPriorityFeePerGas": null,
            "type": "Legacy"
        }
    ]
}

Ethereum Logs

Smart contract logs for events on the Ethereum mainnet.

Ethereum logs aren't necessarily sent in the order they appear in the block, however a previous block's logs will always come before a later block's logs

Schema

Ethereum Logs

Subscribe

{"action": "subscribe", "channel": "ethereum_logs"}

Unsubscribe

{"action": "unsubscribe", "channel": "ethereum_logs"}

Initial Response

{
    "message": "Subscribed to ethereum_logs"
}

Example message

{
    "feed": "ethereum_logs",
    "data": [
        {
            "atomTimestamp": 1671629008834904,
            "blockTimestamp": "2022-12-21T13:23:23Z",
            "logIndex": 938,
            "transactionIndex": 337,
            "transactionHash": "0xe730d67eb3d4efb8a2287a9473154d683768a26d1f0a657678a6ceb942c26ede",
            "blockHash": "0xbe815537e43b18f24777e97e1bfdf5ef6a0cdbb0d57b7c7afecc1531efd3cf22",
            "blockNumber": 16233349,
            "address": "0x06450dee7fd2fb8e39061434babcfc05599a6fb8",
            "data": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "topic1": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "topic2": "0x0000000000000000000000001c5a012a856b64995c78592558623c7fbf9f235d",
            "topic3": null
        },
        {
            "atomTimestamp": 1671629008834904,
            "blockTimestamp": "2022-12-21T13:23:23Z",
            "logIndex": 939,
            "transactionIndex": 337,
            "transactionHash": "0xe730d67eb3d4efb8a2287a9473154d683768a26d1f0a657678a6ceb942c26ede",
            "blockHash": "0xbe815537e43b18f24777e97e1bfdf5ef6a0cdbb0d57b7c7afecc1531efd3cf22",
            "blockNumber": 16233349,
            "address": "0x06450dee7fd2fb8e39061434babcfc05599a6fb8",
            "data": "0x0000000000000000000000000000000000000000000388d251a56ed7e22c0000",
            "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "topic1": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "topic2": "0x000000000000000000000000c7efcec7bc2bda4c49baafc52df016d15bc28353",
            "topic3": null
        }
    ]
}

Ethereum Token Transfers

Specific contract logs for token transfer events, decoded so you can derive the value of the transfer as well as the token and addresses involved.

Schema

Ethereum Token Transfers

Subscribe

{"action": "subscribe", "channel": "ethereum_token_transfers"}

Unsubscribe

{"action": "unsubscribe", "channel": "ethereum_token_transfers"}

Initial Response

{
    "message": "Subscribed to ethereum_token_transfers"
}

Example message

{
    "feed": "ethereum_token_transfers",
    "data": [
        {
            "atomTimestamp": 1671629008834904,
            "blockTimestamp": "2022-12-21T13:23:23Z",
            "tokenAddr": "0x06450dee7fd2fb8e39061434babcfc05599a6fb8",
            "fromAddr": "0000000000000000000000000000000000000000",
            "toAddr": "f5857f30bd6a4571b887df6336e9a97102e4fe30",
            "value": "0",
            "transactionHash": "0xc97483ec0be2415fa8788bae9693d22ad7aafde092916915ef040b6e1423a3e9",
            "logIndex": 281,
            "blockNumber": 16233349,
            "blockHash": "0xbe815537e43b18f24777e97e1bfdf5ef6a0cdbb0d57b7c7afecc1531efd3cf22"
        },
        {
            "atomTimestamp": 1671629008834904,
            "blockTimestamp": "2022-12-21T13:23:23Z",
            "tokenAddr": "0x06450dee7fd2fb8e39061434babcfc05599a6fb8",
            "fromAddr": "0000000000000000000000000000000000000000",
            "toAddr": "c7efcec7bc2bda4c49baafc52df016d15bc28353",
            "value": "4272891999999999757778944",
            "transactionHash": "0x2dc4445f503b8e72204cd5b42f7bf030962753ebfe374b398bbc6ae3e79328f9",
            "logIndex": 372,
            "blockNumber": 16233349,
            "blockHash": "0xbe815537e43b18f24777e97e1bfdf5ef6a0cdbb0d57b7c7afecc1531efd3cf22"
        }
    ]
}

Dex Trades

Normalised trades data for Ethereum DEXes.

Unlike off-chain trades, subscribing to Dex Trades for a specific DEX subscribes you to trades on all the supported symbols for that DEX

Schema

Dex Trades

Subscribe

{"action": "subscribe", "channel": "dex_trades", "exchange": "uniswap-v2"}

Unsubscribe

{"action": "unsubscribe", "channel": "dex_trades", "exchange": "uniswap-v2"}

Initial Response

{
    "message": "Subscribed to uniswap-v2_dex_trades"
}

Example message

{
    "feed": "dex_trades",
    "exchange": "uniswap-v2",
    "data": [
        {
            "atomTimestamp": 1671629393390245,
            "blockTimestamp": "2022-12-21T13:29:47Z",
            "maker": null,
            "taker": "0x8DC4B56eF4a2A1272f7E652bBDD3b6c3a84667C4",
            "tokenBought": "WETH",
            "tokenSold": "USDC",
            "tokenBoughtAddr": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "tokenSoldAddr": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "amountBought": "0.410246785243596979000000",
            "amountSold": "500.000000000000000000000000",
            "logIndex": 92,
            "transactionHash": "0x3140e2227277222bc75c91e68e393355c978550c0ca42ef275ceb40fa40a2836",
            "blockHash": "0x9628455f9fd48d7424155d3b4373d44232020c0eb78bdc262775e07fc952a76c",
            "blockNumber": 16233380,
            "pairAddr": "0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc"
        }
    ]
}

Dex Liquidity

Liquidity updates for Ethereum DEXes.

Schema

Dex Liquidity

Subscribe

{"action": "subscribe", "channel": "dex_liquidity", "exchange": "uniswap-v2"}

Unsubscribe

{"action": "unsubscribe", "channel": "dex_liquidity", "exchange": "uniswap-v2"}

Initial Response

{
    "message": "Subscribed to uniswap-v2_dex_liquidity"
}

Example message

{
    "feed": "dex_liquidity",
    "exchange": "uniswap-v2",
    "data": [
        {
            "atomTimestamp": 1671629393390245,
            "blockTimestamp": "2022-12-21T13:29:47Z",
            "eventType": "add",
            "owner": "0x8DC4B56eF4a2A1272f7E652bBDD3b6c3a84667C4",
            "token0": "WETH",
            "token1": "USDC",
            "token0Addr": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "token1Addr": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "amount0": "0.410246785243596979000000",
            "amount1": "500.000000000000000000000000",
            "logIndex": 92,
            "transactionHash": "0x3140e2227277222bc75c91e68e393355c978550c0ca42ef275ceb40fa40a2836",
            "blockHash": "0x9628455f9fd48d7424155d3b4373d44232020c0eb78bdc262775e07fc952a76c",
            "blockNumber": 16233380,
            "pairAddr": "0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc"
        }
    ]
}
PreviousSupported Feeds and SymbolsNextFAQs

Last updated