ChainStream API
ChainStream APIs are a way to stream Solana transaction, slot, and block updates directly from the validator.
Introduction
The ChainStream APIs allow you to stream transaction, slot, and block updates in real-time using an RPC PubSub WebSocket. Why does this matter? Having the latest blocks, slot updates (whether they're processed, rooted or confirmed) and real-time processed commitment-level transactions streamed to your application is critical for some applications. This API intends to solve those needs by streaming this data in real-time.
Another important benefit of the ChainStream API is that it consolidates updates from multiple validators ensuring that you will never miss a notification. This is especially important for applications that require high-availability and reliability.
The ChainStream API is available to all customers on the Scale Mode plan. Scale Mode comes with one ChainStream subscription and you can add up to nine (9) additional subscriptions for $0.14/hour each.
Enabling ChainStream API
In order to use the ChainStream API, you need to navigate to the ChainStream API page from the left-side navigation menu. Once there, click Enable ChainStream API.
Once enabled, you can select the number of streams you want to subscribe to. You can add up to 10 streams in total. Please note that one stream is included in the Scale Mode plan, and additional streams are billed at $0.14/hour.
Anatomy of a ChainStream API Subscription Request
ChainStream API uses the JSON RPC 2.0 Spec which you can check out here. Beyond the standard specification, each notification subscription request requires the following params:
1. network
The network you want to subscribe to. Currently, we support solana-mainnet, solana-devnet will be available soon.
2. verified
Whether or not you want to receive verified transactions. If you set this to true, you will only receive transactions that have been verified by ChainStream to have come from multiple validators. Please note: setting this to true will delay the notification by one slot due to the verification process.
Setting this param to false will report the notification as quickly as possible without waiting for multiple validators to report the same notification.
Anatomy of a ChainStream API Notification
Every ChainStream API notification will contain the following:
1. subscription
This is the subscription ID that you received when you subscribed to the notification. You will need this to unsubscribe from the notification.
2. result
This is the actual notification. The contents of this will vary depending on the notification type. See below for more details.
Supported Subscription Types
The ChainStream API allows you to subscribe to the following notifications:
Below we will cover how to subscribe to each notification type.
Transaction Notifications
Receive a notification anytime a transaction takes place on your specified network.
Filters
With ChainStream transaction notifications, you can optionally filter transactions by the following criteria:
excludeVotes- Exclude transactions that are votes from the stream. Default:falseaccountKeys- Filter transactions by account keys. Default:null. Options include:all- All the specified account keys must be present in the transactiononeOf- At least one of the account keys must be present in the transactionexclude- Exclude transactions that contain any of the specified account keys
For accountKeys, if both all and oneOf are supplied, then ChainStream will report transactions that contain all keys in all and at least one key in oneOf. If exclude is supplied, then ChainStream will exclude transactions that contain any of the keys in exclude.
If no filters are supplied, you will receive all transactions at the processed commitment level.
Subscribe Request
{
"jsonrpc": "2.0",
"id": 123,
"method": "chainstream.transactionsSubscribe",
"params": {
"network": "solana-mainnet",
"verified": true,
"filter": {
"excludeVotes": false
}
}
}
{
"jsonrpc": "2.0",
"id": 123,
"method": "chainstream.transactionsSubscribe",
"params": {
"network": "solana-mainnet",
"verified": true,
"filter": {
"excludeVotes": false,
"accountKeys": {
"all": [
"vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg",
"4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA"
],
"oneOf": [
"vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg",
"4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA"
],
"exclude": ["BGsqMegLpV6n6Ve146sSX2dTjUMj3M92HnU8BbNRMhF2"]
}
}
}
}
Subscribe Response
If successful, you should receive a response like below:
Save the subscription ID from the response here, you will need this to unsubscribe in the future.
{
"jsonrpc": "2.0",
"result": 446257156701906,
"id": 123
}
Notification
Example of periodic (streaming) chainstream.transactionNotification(s):
Note: The blockTime will be null for transactions whose slotStatus is processed. This is to be expected, as the block has not been confirmed by the cluster yet.
{
"jsonrpc": "2.0",
"method": "transactionNotification",
"params": {
"subscription": 3,
"result": {
"context": {
"index": 604,
"isVote": false,
"nodeTime": "2023-11-28T19:36:09.977998269Z",
"signature": "3EJbaJmbMgS1SiG6HcDJFXrMtmvxBgEJQah5MLZMxp23TafZkgybBEvULBS6LC1mJEYnv5J3UoQ3tFiPfPG5qF34",
"slotStatus": "processed"
},
"value": {
"blockTime": null,
"meta": {
"err": {
"InstructionError": [
1.0,
{
"Custom": 6036.0
}
]
},
"fee": 5000,
"innerInstructions": [],
"loadedAddresses": {
"readonly": [],
"writable": []
},
"logMessages": [
"Program ComputeBudget111111111111111111111111111111 invoke [1]",
"Program ComputeBudget111111111111111111111111111111 success",
"Program whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc invoke [1]",
"Program log: Instruction: Swap",
"Program log: fee_growth: 451160579113",
"Program log: AnchorError occurred. Error Code: AmountOutBelowMinimum. Error Number: 6036. Error Message: Amount out below minimum threshold.",
"Program whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc consumed 41335 of 65536 compute units",
"Program whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc failed: custom program error: 0x1794"
],
"postBalances": [
10250627025, 994435781, 6448790698383, 48051806330590, 2039280, 2039280, 70407360,
70407360, 70407360, 1, 1141440, 934087680, 0
],
"postTokenBalances": [
{
"accountIndex": 2,
"mint": "So11111111111111111111111111111111111111112",
"owner": "AK47XL44WVb1sFp6ehkUwMAmPDuSyTtnVv7RY6Ys2dSy",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "6448788659103",
"decimals": 9,
"uiAmount": 6448.788659103,
"uiAmountString": "6448.788659103"
}
},
{
"accountIndex": 3,
"mint": "So11111111111111111111111111111111111111112",
"owner": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "48051804291310",
"decimals": 9,
"uiAmount": 48051.80429131,
"uiAmountString": "48051.80429131"
}
},
{
"accountIndex": 4,
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"owner": "AK47XL44WVb1sFp6ehkUwMAmPDuSyTtnVv7RY6Ys2dSy",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "12665588254",
"decimals": 6,
"uiAmount": 12665.588254,
"uiAmountString": "12665.588254"
}
},
{
"accountIndex": 5,
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"owner": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "2653068643838",
"decimals": 6,
"uiAmount": 2653068.643838,
"uiAmountString": "2653068.643838"
}
}
],
"preBalances": [
10250632025, 994435781, 6448790698383, 48051806330590, 2039280, 2039280, 70407360,
70407360, 70407360, 1, 1141440, 934087680, 0
],
"preTokenBalances": [
{
"accountIndex": 2,
"mint": "So11111111111111111111111111111111111111112",
"owner": "AK47XL44WVb1sFp6ehkUwMAmPDuSyTtnVv7RY6Ys2dSy",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "6448788659103",
"decimals": 9,
"uiAmount": 6448.788659103,
"uiAmountString": "6448.788659103"
}
},
{
"accountIndex": 3,
"mint": "So11111111111111111111111111111111111111112",
"owner": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "48051804291310",
"decimals": 9,
"uiAmount": 48051.80429131,
"uiAmountString": "48051.80429131"
}
},
{
"accountIndex": 4,
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"owner": "AK47XL44WVb1sFp6ehkUwMAmPDuSyTtnVv7RY6Ys2dSy",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "12665588254",
"decimals": 6,
"uiAmount": 12665.588254,
"uiAmountString": "12665.588254"
}
},
{
"accountIndex": 5,
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"owner": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "2653068643838",
"decimals": 6,
"uiAmount": 2653068.643838,
"uiAmountString": "2653068.643838"
}
}
],
"rewards": [],
"status": {
"Err": {
"InstructionError": [
1.0,
{
"Custom": 6036.0
}
]
}
}
},
"slot": 232812811,
"transaction": {
"message": {
"accountKeys": [
"AK47XL44WVb1sFp6ehkUwMAmPDuSyTtnVv7RY6Ys2dSy",
"7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
"F9EgG1oDJo8YyLc3ohEURvW6c5vPTsiHNDMBbYMKGdLB",
"9RfZwn2Prux6QesG1Noo4HzMEBv3rPndJ2bN2Wwd6a7p",
"8BuHWU9dXykNNS8cnVSbV1JY648UkGm6dfRbSfmE2grf",
"BVNo8ftg2LkkssnWT4ZWdtoFaevnfD6ExYeramwM27pe",
"Yb2axPXvJG3ouAQ4ZBUzSqmQjbgKDkhqQPsd9Mqq3jp",
"FLNNqPmeaSEdmq7xVVTTt5ErEVmpg4kcnRrffg9D6PQr",
"CrG3tbpzisatcBwVRfiuJJvWXUFewmxxYYKEh7L42nrd",
"ComputeBudget111111111111111111111111111111",
"whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc",
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"6vK8gSiRHSnZzAa5JsvBF2ej1LrxpRX21Y185CzP4PeA"
],
"addressTableLookups": [],
"header": {
"numReadonlySignedAccounts": 0,
"numReadonlyUnsignedAccounts": 4,
"numRequiredSignatures": 1
},
"instructions": [
{
"accounts": [],
"data": "E64fMy",
"programIdIndex": 9
},
{
"accounts": [11, 0, 1, 2, 3, 4, 5, 6, 7, 8, 12],
"data": "59p8WydnSZtRpTLDVVek9vtNmpBYwynq1ukXnjA1cvWmHCquRh8cpXDZU4",
"programIdIndex": 10
}
],
"recentBlockhash": "D3eHsPe4Ecy9PwMdiNbXxTSRPMDXzibMLSXyDMRmEbdm"
},
"messageHash": "3gYBCTjxJ4oCLVJCfNRsJERDuqUtk8MVctQuJ8vCMN3F",
"signatures": [
"3EJbaJmbMgS1SiG6HcDJFXrMtmvxBgEJQah5MLZMxp23TafZkgybBEvULBS6LC1mJEYnv5J3UoQ3tFiPfPG5qF34"
]
}
}
}
}
}
Unsubscribe
Unsubscribe using subscription ID, which can be found in each notification from the stream:
{
"jsonrpc": "2.0",
"id": 123,
"method": "chainstream.transactionsUnsubscribe",
"params": [446257156701906]
}
Block Notifications
Receive a notification every time a new block is processed by a validator.
Subscription Request
{
"jsonrpc": "2.0",
"id": "123",
"method": "chainstream.blocksSubscribe",
"params": {}
}
Subscribe Response
If successful, you should receive a response like below:
Save the subscription ID from the response here, you will need this to unsubscribe in the future.
{
"jsonrpc": "2.0",
"result": 32026100100140,
"id": 123
}
notifications
Example of periodic (streaming) block notifications:
Result:
context: this object contains contextual data related to the block notificationvalue: a block notification. See an example notification below for a list of fields returned.
{
"jsonrpc": "2.0",
"method": "blockNotification",
"params": {
"subscription": 32026100100140,
"result": {
"context": {
"nodeTime": "2023-11-28T20:30:18.891246638Z"
},
"value": {
"slot": 232820203,
"blockhash": "4af1ziNjnJjAM4Wc5dbs5oLCfZSUX3et3SBpYamUVnqS",
"rewards": [
{
"pubkey": "",
"lamports": 25987280,
"postBalance": 1935203524,
"rewardType": 0,
"commission": null
}
],
"blockTime": "2023-11-28T20:30:18Z",
"blockHeight": 214481453,
"parentSlot": 232820202,
"parentBlockhash": "5Mg2RJQqdCibdWmwxYhrszJz4HrXu1Tq7B4xnJwEYnQN",
"executedTransactionCount": 1037
}
}
}
}
Unsubscribe
Unsubscribe using subscription ID, which can be found in each notification from the stream:
{
"jsonrpc": "2.0",
"id": 123,
"method": "chainstream.blocksUnsubscribe",
"params": [446257156701906]
}
Slot Notifications
Receive a notification anytime a slot is updated by a validator.
Subscription Request
{
"jsonrpc": "2.0",
"id": "123",
"method": "chainstream.slotUpdatesSubscribe",
"params": {
"network": "solana-mainnet",
"verified": true
}
}
Subscription Response
If successful, you should receive a response like below:
Save the subscription ID from the response here, you will need this to unsubscribe in the future.
{
"jsonrpc": "2.0",
"result": 6296444419224395,
"id": 123
}
Notification
Receive a notification anytime a slot is updated by the validator.
{
"jsonrpc": "2.0",
"method": "slotUpdateNotification",
"params": {
"subscription": 6296444419224395,
"result": {
"context": {
"nodeTime": "2023-11-28T20:47:23.363515459Z"
},
"value": {
"slot": 232822534,
"parent": 232822533,
"status": "processed"
}
}
}
}
Unsubscribe
Unsubscribe to slot updates using chainstream.slotUpdatesUnsubscribe method:
{
"jsonrpc": "2.0",
"id": 123,
"method": "chainstream.slotUpdatesUnsubscribe",
"params": [6296444419224395]
}
Using the ChainStream APIs
Make sure you have access. To use the ChainStream API you'll need to be subscribed to our Scale Mode plan and enable ChainSteam in the platform.
Establish a WebSocket connection to the ChainStream API endpoint:
This endpoint is different than the Syndica RPC endpoint available on the platform.
wss://api.syndica.io/
Example of sending JSON RPC messages via WebSocket client in Node.JS
const url = 'wss://api.syndica.io/'
const connection = new WebSocket(url)
const slotUpdatesSubscribeReq = {
jsonrpc: '2.0',
id: '123',
method: 'chainstream.slotUpdatesSubscribe',
params: {},
}
connection.onopen = () => {
connection.send(JSON.stringify(slotUpdatesSubscribeReq))
}
connection.onerror = (error) => {
console.log(`WebSocket error: ${error}`)
}
connection.onmessage = (e) => {
console.log(e.data)
// {
// "jsonrpc": "2.0",
// "method": "chainstream.slotUpdateNotification",
// "params": {
// "subscription": "09c63354-70b2-4e4b-8dcb-45c9a981d54f",
// "result": {
// "slot": 150867846,
// "parent": 150867845,
// "status": "processed" // or: "rooted", "confirmed"
// }
// }
// }
}
Timeouts
There is a five (5) second timeout between creating a WebSocket connection (initial HTTP 101 connection upgrade request) and initiating a subscription (the actual JSON WebSocket RPC request). Clients must send the JSON RPC request within this 5 second window after opening the connection. This is often taken care of for you by most WebSocket client implementations, but tools such as Postman separate out these stages for testing purposes.
Once a subscription has been established there is a sixty (60) second timeout for messages. In other words, if the subscription has no traffic over any 60 second window, the subscription is automatically closed. To avoid this, clients must send PING messages periodically (for example, once every 30 seconds) to keep the subscription alive during periods with no notifications.
import WebSocket from "ws";
const TOKEN = "Your token here!";
const wsUrl = `wss://api.syndica.io/api-token/${TOKEN}`;
const ws_transactions: WebSocket = new WebSocket(wsUrl);
var n_tx = 0;
ws_transactions.on("open", function open(): void {
console.log("connected to Chainstream API");
// Send the specified request to subscribe.
// The request's filter below is intentionally set to produce no/very low volume of messages,
// keeping this subscription alive requires the client to send PING messages.
ws_transactions.send(
JSON.stringify({
jsonrpc: "2.0",
id: 123,
method: "chainstream.transactionsSubscribe",
params: {
network: "solana-mainnet",
verified: false,
filter: {
accountKeys: {
all: [
"BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY",
"675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
"ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
"SysvarRent111111111111111111111111111111111",
],
},
},
},
})
);
// Send PING messages every 30s.
setInterval(() => {
ws_transactions.ping();
}, 30000);
});
ws_transactions.on("message", function incoming(data: WebSocket.Data): void {
// The first message is always the subscription result.
if (n_tx == 0) {
console.log("transaction subscription result", JSON.parse(data.toString()));
} else {
// Deserialize.
let tx = JSON.parse(data.toString());
// Add a timestamp field and log out the transaction signature.
tx.utc_timestamp = new Date().toUTCString();
let sig = tx.params.result.context.signature;
let ts = tx.utc_timestamp;
console.log(`[${ts}] Transaction ${sig} received`);
}
n_tx++;
});
ws_transactions.on("close", function close(): void {
console.log("Disconnected from the server.");
});
ws_transactions.on("error", function error(err: Error): void {
console.error("WebSocket error:", err);
});