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

aptos

Aptos

arbitrum-one

Arbitrum One

avalanche

Avalanche

base

Base

beacon-chain

Beacon Chain

bitcoin

Bitcoin

bitcoin-cash

Bitcoin Cash

bnb

BNB

bob

BOB

botanix

Botanix

cardano

Cardano

dash

Dash

digibyte

DigiByte

dogecoin

Dogecoin

ecash

eCash

ethereum

Ethereum

ethereum-classic

Ethereum Classic

fantom

Fantom

gnosis-chain

Gnosis Chain

groestlcoin

Groestlcoin

handshake

Handshake

linea

Linea

litecoin

Litecoin

monero

Monero

moonbeam

Moonbeam

opbnb

opBNB

optimism

Optimism

peercoin

Peercoin

polkadot

Polkadot

polygon

Polygon

polygon-zkevm

Polygon zkEVM

rootstock

Rootstock

sei-evm

Sei EVM

solana

Solana

ton

TON

tron

TRON

xrp-ledger

XRP Ledger

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.

Type / to focus