WebSocket
Subscribe to trades, candles, pools and new launches, and get each update the moment it is indexed instead of polling the REST API.
Connecting
wss://api.notinal.xyz/v1/ws- No key is needed. Every message, both ways, is a JSON text frame.
- Each IP address can hold 5 connections, with up to 50 subscriptions on each.
- Send
{"op":"ping"}at least every 30 seconds. The server answers{"op":"pong"}, and closes a connection that has been silent for 60. - WebSocket traffic does not count against the REST API's 120 requests a minute.
Subscribing
Send subscribe with a channel and the channel's parameters. The server confirms with subscribed, then sends an update each time something changes.
{
"op": "subscribe",
"channel": "trades",
"coin": "0x7e57000000000000000000000000000000000005"
}{
"op": "subscribed",
"channel": "trades",
"coin": "0x7e57000000000000000000000000000000000005"
}To stop, send the same message with unsubscribe, and the server confirms with unsubscribed.
{
"op": "unsubscribe",
"channel": "trades",
"coin": "0x7e57000000000000000000000000000000000005"
}A message the server cannot act on gets an error, and the connection stays open:
{
"op": "error",
"code": "invalid_request",
"message": "Unknown channel: trade."
}Error codes are the REST API's, plus too_many_subscriptions past 50 on one connection.
Channels
| Channel | Parameters | Sends |
|---|---|---|
trades | coin | Every trade in a coin, on its curve or, after graduation, in its pool. |
candles | coin, interval | The open candle each time a trade changes it, at 1m, 5m, 15m or 1h. A new candle starts each interval. |
pools | pool | A pool's price, reserves and 24-hour numbers after each swap or change in liquidity, at most once a second. Leave out pool for every pool. |
launches | none | Every new coin, as it is created. |
Updates carry the same objects as the REST reference: a trade, a candle, a coin.
trades
{
"op": "subscribe",
"channel": "trades",
"coin": "0x7e57000000000000000000000000000000000005"
}{
"channel": "trades",
"coin": "0x7e57000000000000000000000000000000000005",
"data": {
"time": 1790992659,
"side": "buy",
"coinAmount": "7464875.4",
"pairAmount": "0.1177667",
"priceUsd": "0.00000362851",
"valueUsd": "27.09",
"trader": "0x1b3021a71c884b2ebb936521d06a004125ad6e64",
"tx": "0x882a45b33cfb15a3fc09d72b843f7f2436b2b35a306db34ff2bf51b98b6cd576"
}
}candles
{
"op": "subscribe",
"channel": "candles",
"coin": "0x7e57000000000000000000000000000000000005",
"interval": "1m"
}{
"channel": "candles",
"coin": "0x7e57000000000000000000000000000000000005",
"interval": "1m",
"data": {
"time": 1790992620,
"open": "0.00000358739",
"high": "0.00000365323",
"low": "0.00000353349",
"close": "0.00000362851",
"volumeUsd": "36.44"
}
}pools
{
"op": "subscribe",
"channel": "pools",
"pool": "0x7197b1af3521b92ed8f1ce8dba175cdd55373388"
}{
"channel": "pools",
"pool": "0x7197b1af3521b92ed8f1ce8dba175cdd55373388",
"data": {
"price": "89",
"baseReserve": "56.60764",
"quoteReserve": "4801.92",
"tvlUsd": "9840.00",
"volume24hUsd": "6120.00",
"fees24hUsd": "3.06"
}
}launches
{
"op": "subscribe",
"channel": "launches"
}{
"channel": "launches",
"data": {
"address": "0x7e57000000000000000000000000000000000006",
"symbol": "TEST6",
"name": "test6",
"pair": "HOOD",
"image": "https://notinal.xyz/tokens/test6.svg",
"creator": "0x60718293a4b5c6d7e8f9012a3b4c5d6e7f8091a2",
"createdAt": 1790992680,
"priceUsd": "0.00000352",
"marketCapUsd": "3520.00",
"volume24hUsd": "190.00",
"change24h": 0.6,
"holders": 7,
"curveProgress": 5,
"graduated": false
}
}A complete client
A browser client that follows one coin's trades and every new launch, keeps the connection alive and reconnects when it drops. In Node 22 and later, WebSocket is built in too.
// onTrade, onLaunch and onError are your own handlers.
const COIN = "0x7e57000000000000000000000000000000000005";
function connect(delay = 1000) {
const ws = new WebSocket("wss://api.notinal.xyz/v1/ws");
let ping;
ws.addEventListener("open", () => {
delay = 1000;
ws.send(JSON.stringify({ op: "subscribe", channel: "trades", coin: COIN }));
ws.send(JSON.stringify({ op: "subscribe", channel: "launches" }));
// The server closes a connection that has been silent for 60 seconds.
ping = setInterval(() => ws.send(JSON.stringify({ op: "ping" })), 30_000);
});
ws.addEventListener("message", (event) => {
const message = JSON.parse(event.data);
if (message.channel === "trades") onTrade(message.data);
if (message.channel === "launches") onLaunch(message.data);
if (message.op === "error") onError(message);
});
// Subscriptions end with the connection: reconnect, waiting longer each time, and subscribe again.
ws.addEventListener("close", () => {
clearInterval(ping);
setTimeout(() => connect(Math.min(delay * 2, 30_000)), delay);
});
}
connect();Updates sent while you were disconnected are not replayed. After a reconnect, fetch anything you may have missed from the REST API, such as the latest trades, before you rely on the stream again.
