notional

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

URL
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.

You send
{
  "op": "subscribe",
  "channel": "trades",
  "coin": "0x7e57000000000000000000000000000000000005"
}
The server confirms
{
  "op": "subscribed",
  "channel": "trades",
  "coin": "0x7e57000000000000000000000000000000000005"
}

To stop, send the same message with unsubscribe, and the server confirms with unsubscribed.

You send
{
  "op": "unsubscribe",
  "channel": "trades",
  "coin": "0x7e57000000000000000000000000000000000005"
}

A message the server cannot act on gets an error, and the connection stays open:

Error
{
  "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

ChannelParametersSends
tradescoinEvery trade in a coin, on its curve or, after graduation, in its pool.
candlescoin, intervalThe open candle each time a trade changes it, at 1m, 5m, 15m or 1h. A new candle starts each interval.
poolspoolA 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.
launchesnoneEvery new coin, as it is created.

Updates carry the same objects as the REST reference: a trade, a candle, a coin.

trades

Subscribe
{
  "op": "subscribe",
  "channel": "trades",
  "coin": "0x7e57000000000000000000000000000000000005"
}
Update
{
  "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

Subscribe
{
  "op": "subscribe",
  "channel": "candles",
  "coin": "0x7e57000000000000000000000000000000000005",
  "interval": "1m"
}
Update
{
  "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

Subscribe
{
  "op": "subscribe",
  "channel": "pools",
  "pool": "0x7197b1af3521b92ed8f1ce8dba175cdd55373388"
}
Update
{
  "channel": "pools",
  "pool": "0x7197b1af3521b92ed8f1ce8dba175cdd55373388",
  "data": {
    "price": "89",
    "baseReserve": "56.60764",
    "quoteReserve": "4801.92",
    "tvlUsd": "9840.00",
    "volume24hUsd": "6120.00",
    "fees24hUsd": "3.06"
  }
}

launches

Subscribe
{
  "op": "subscribe",
  "channel": "launches"
}
Update
{
  "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.

JavaScript
// 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.

Welcome to notional

notional is an interface to smart contracts on HyperEVM. You stay in control of your wallet, every transaction is final, and memecoins and tokenized stocks can lose all of their value.