WebSocket API

The WebSocket API provides real-time data from the 3xpl.com blockchain explorer.

As a developer-friendly solution, we offer AsyncAPI based document: stream.3xpl.net-asyncapi.yml. You can use the AsyncAPI Generator as a tool to generate code examples (SDKs) in your preferred language based on the provided AsyncAPI document.

Common features

The base endpoint is: wss://stream.3xpl.net. A public beta server is available without the need for authorization.
Once the socket is open, you can subscribe to a public channel by sending a subscribe request message. Every message is JSON-encoded.
Every message is JSON encoded.
The special JSON value null is used as a PING/PONG message. PINGs sent by a server, a client should answer with PONGs upon receiving PING. Alternatively, you can use these messages to detect broken connections, particularly when nothing has been received from the server for a considerable amount of time. The server sends a PING message every 25 seconds.
The server supports the reconnect scenario and automatically provides a history of missed data.

Connection scenario

Receive a JWT token using:
- personal customer area (the token expiration can be set manually);
- service endpoint https://3xpl.com/get-websockets-token (the token valid for 10 minutes).
Connect to base endpoint wss://stream.3xpl.net
Once the connection is established, the server expects the following messages:
- connect request message: {"connect":{"token":"{JWT_TOKEN}"},"id":1} where {JWT_TOKEN} is JWT token received in previous step;
- subscribe request message: {"subscribe":{"channel":""},"id":2} where channel is the name of the channel to subscribe to.

You can subscribe up to 10 channels using one connection.

Channel history and recovery

The WebSocket Server maintains a publication history for certain channels, with the history size capped at 100 messages.

To receive the history for a channel, send the following message: {"history":{"channel":"","limit":1,"reverse":true},"id":3} where channel is the name of the channel, limit is number of history messages you want, reverse indicates the direction of messages (from the most recent to the earliest).

Messages format

Every message comprises two section:

data: this contains general information provided by the channel.
context: this section offers additional technical information

Available blockchains

Every channel name contains {:blockchain} parameter.
You can get list of available blockchains directly from api main stats endpoint: https://api.3xpl.com/ (api token key required)

List of available blockchains

Id	Title
arbitrum-one	Arbitrum One
avalanche	Avalanche
base	Base
beacon-chain	Beacon Chain
bitcoin	Bitcoin
bitcoin-cash	Bitcoin Cash
bnb	BNB
cardano	Cardano
dash	Dash
digibyte	DigiByte
dogecoin	Dogecoin
ethereum	Ethereum
fantom	Fantom
gnosis-chain	Gnosis Chain
handshake	Handshake
litecoin	Litecoin
monero	Monero
opbnb	opBNB
optimism	Optimism
peercoin	Peercoin
polkadot	Polkadot
polygon	Polygon
polygon-zkevm	Polygon zkEVM
solana	Solana
ton	TON
tron	TRON
zcash	Zcash

Available channels

SUB

{blockchain}/blocks

Stream information about new blocks in blockchain

Parameters:

Name / type	Description
blockchain string	id of blockchain to receive blocks from

Response:

object {}
- data array [] List of blocks
  - object {} Block object
    - block integer Block identifier
    - hash string Block hash
    - time string Timestamp when block issued
    - events object {} Key-value object with events count by module
      - {:module} integer Events count
- context object {}
  - time string Time when message was produced

Response examples:

Bitcoin block number 500000

{
    data: [
        {
            block: 500000,
            hash: "00000000000000000024fb37364cbf81fd49cc2d51c09c75c35433c3a1945d04",
            time: "2017-12-18T18:35:25.000000Z",
            events: {
                bitcoin-main: 13340,
                bitcoin-omni: 420
            }
        }
    ],
    context: {
        time: "0.59455600 1685039844"
    }
}

SUB

{blockchain}/events

Stream information about new events in blockchain

Parameters:

Name / type	Description
blockchain string	id of blockchain to receive events from

Response:

object {}
- data array [] List of events
  - object {} Event object
    - blockchain string
    - module string Module in which the event occurred
    - block integer Number of block in which the event included
    - transaction string Hash of transaction contains the event
    - sort_key integer Sorting number
    - address string Address affected by the event
    - currency string Effect currency
    - effect string Amount in currency which address effected
    - failed boolean Shows is event failed by any reason
    - extra null
    - extra_indexed null
- context object {}
  - time string Time when message was produced

Response examples:

First events in Bitcoin blockchain

{
    data: [
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: 0,
            transaction: "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
            sort_key: 0,
            address: "the-void",
            currency: "bitcoin",
            effect: "-5000000000",
            failed: false,
            extra: null,
            extra_indexed: null
        },
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: 0,
            transaction: "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
            sort_key: 1,
            address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
            currency: "bitcoin",
            effect: "+5000000000",
            failed: false,
            extra: null,
            extra_indexed: null
        }
    ],
    context: {
        time: "2023-03-02T18:24:51.000000Z"
    }
}

SUB

{blockchain}/mempool

Stream information about new events in mempool (if specified blockchain supports it)

Parameters:

Name / type	Description
blockchain string	id of blockchain to receive events from

Response:

object {}
- data array [] List of mempool events
  - object {} Mempool event object
    - blockchain string
    - module string Module in which the event occurred
    - block integer `-1` always
    - transaction string Hash of transaction contains the event
    - sort_key integer Sorting number
    - address string Address affected by the event
    - currency string Effect currency
    - effect string Amount in currency which address effected
    - failed boolean Shows is event failed by any reason
    - extra null
    - extra_indexed null
- context object {}
  - time string Time when message was produced

Response examples:

First events in Bitcoin blockchain

{
    data: [
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: -1,
            transaction: "63381b941dbe21d6b7d03cab158118d74c7c313eb4c9164abf64f1293702923a",
            sort_key: 326,
            address: "bc1qkcwtu2k9jjhyvlx804xx5ae786yksqhvju46ml",
            currency: "bitcoin",
            effect: "-723449",
            failed: false,
            extra: null,
            extra_indexed: null
        },
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: -1,
            transaction: "63381b941dbe21d6b7d03cab158118d74c7c313eb4c9164abf64f1293702923a",
            sort_key: 325,
            address: "bc1qph5wssklxwsl50vyhstlg232nzqwp8sfws2zqm",
            currency: "bitcoin",
            effect: "-910585",
            failed: false,
            extra: null,
            extra_indexed: null
        }
    ],
    context: {
        time: "2023-03-02T16:20:00.000000Z"
    }
}

SUB

{blockchain}/transaction/{hash}

Receive event when a mempool transaction will be included in the block

Parameters:

Name / type	Description
blockchain string	id of blockchain to receive events from
hash string	Transaction hash

Response:

object {} Transaction object
- module string Module in which the transaction processed
- block integer Number of block in which the transaction included
- transaction string Transaction hash
- time string Transaction timestamp

Response examples:

First transaction in Dogecoin blockchain

{
    data: {
        module: "dogecoin-main",
        block: 0,
        transaction: "5b2a3f53f605d62c53e62932dac6925e3d74afa5a4b459745c36d42d0ed26a69",
        time: "2013-12-06T10:25:40.000000Z"
    },
    context: {
        time: "2013-12-06T10:25:40.000000Z"
    }
}

SUB

{blockchain}/address/{hash}

Stream information about new events address affected

Parameters:

Name / type	Description
blockchain string	id of blockchain to receive events from
hash string	Address

Response:

object {}
- data array [] List of events
  - object {} Event object
    - blockchain string
    - module string Module in which the event occurred
    - block integer Number of block in which the event included
    - transaction string Hash of transaction contains the event
    - sort_key integer Sorting number
    - address string Address affected by the event
    - currency string Effect currency
    - effect string Amount in currency which address effected
    - failed boolean Shows is event failed by any reason
    - extra null
    - extra_indexed null
- context object {}
  - time string Time when message was produced

Response examples:

Some recently events affected to first address in Bitcoin blockchain

{
    data: [
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: 779007,
            transaction: "685e1c7bd823384335e1b3519148622e97a6e6a637bfee339c347e1d994b73bc",
            sort_key: 13093,
            time: "2023-03-02T18:38:33.000000Z",
            currency: "bitcoin",
            effect: "+7491",
            failed: false,
            extra: null,
            extra_indexed: null
        },
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: 779006,
            transaction: "6783e8ef51befa0eb31f12c7e36317ceca1f766f0c7ce2af5c13ede7cffc43de",
            sort_key: 1918,
            time: "2023-03-02T18:24:51.000000Z",
            currency: "bitcoin",
            effect: "+7047",
            failed: false,
            extra: null,
            extra_indexed: null
        }
    ],
    context: {
        time: "2023-03-02T18:24:51.000000Z"
    }
}

SUB

{blockchain}/currency/{hash}

Stream information about new events with provided currency

Parameters:

Name / type	Description
blockchain string	id of blockchain to receive events from
hash string	Currency contract address

Response:

object {}
- data array [] List of events
  - object {} Event object
    - blockchain string
    - module string Module in which the event occurred
    - block integer Number of block in which the event included
    - transaction string Hash of transaction contains the event
    - sort_key integer Sorting number
    - address string Address affected by the event
    - currency string Effect currency
    - effect string Amount in currency which address effected
    - failed boolean Shows is event failed by any reason
    - extra null
    - extra_indexed null
- context object {}
  - time string Time when message was produced

Response examples:

First events in Bitcoin blockchain

{
    data: [
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: 0,
            transaction: "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
            sort_key: 0,
            address: "the-void",
            currency: "bitcoin",
            effect: "-5000000000",
            failed: false,
            extra: null,
            extra_indexed: null
        },
        {
            blockchain: "bitcoin",
            module: "bitcoin-main",
            block: 0,
            transaction: "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
            sort_key: 1,
            address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
            currency: "bitcoin",
            effect: "+5000000000",
            failed: false,
            extra: null,
            extra_indexed: null
        }
    ],
    context: {
        time: "2023-03-02T18:24:51.000000Z"
    }
}

How to get access to data services

Join our Discord server and go to the #faq section, where you can find authorization credentials and keys. We provide free access to data services for students and academics.