DEV Community

Cover image for XRPL WebSocket: Build a Live XRP Whale Alert in Node.js (No API Key)
xrpl.to
xrpl.to

Posted on

XRPL WebSocket: Build a Live XRP Whale Alert in Node.js (No API Key)

The XRP Ledger sends every validated transaction to anyone who subscribes over WebSocket. This guide subscribes to a public server, keeps the XRP payments above a size you choose, and names the exchanges and other large accounts behind them. You need Node.js 22 or later, which has WebSocket built in, and no API key.

1. Subscribe to new ledgers

Connect to wss://s1.xrpl.stream, a public XRP Ledger server, and send a subscribe command.

Request

{
  "id": 1,
  "command": "subscribe",
  "streams": [
    "ledger"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Response

{
  "result": {
    "fee_base": 10,
    "ledger_hash": "D6F736AD58F880B07A9E43A0F3BB9DBD9BA5080BE24AFFA34B4CEFEA850D2426",
    "ledger_index": 108488925,
    "ledger_time": 848634060,
    "network_id": 0,
    "reserve_base": 1000000,
    "reserve_inc": 200000,
    "validated_ledgers": "107936549-108488925"
  },
  "id": 1,
  "status": "success",
  "type": "response"
}
Enter fullscreen mode Exit fullscreen mode

From then on, a ledgerClosed message arrives every 3 to 4 seconds:

{
  "fee_base": 10,
  "ledger_hash": "7B17D65E25EE4E028283989F4A57D11DA5A41DC76DEF5782FEA6E67FEC16FD9B",
  "ledger_index": 108488927,
  "ledger_time": 848634062,
  "network_id": 0,
  "reserve_base": 1000000,
  "reserve_inc": 200000,
  "txn_count": 54,
  "type": "ledgerClosed",
  "validated_ledgers": "107936549-108488927"
}
Enter fullscreen mode Exit fullscreen mode
  • txn_count: transactions in that ledger.
  • reserve_base and reserve_inc: the account reserve, 1 XRP, and 0.2 XRP for each object an account owns, both in drops (1 XRP = 1,000,000 drops).
  • validated_ledgers: the ledgers this server holds. It keeps recent history; older ledgers need a full-history server.

2. Subscribe to every transaction

Request

{
  "command": "subscribe",
  "streams": [
    "transactions"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Response

One message per validated transaction, dozens a second. This is a real one, shortened:

{
  "type": "transaction",
  "engine_result": "tesSUCCESS",
  "ledger_index": 108488927,
  "validated": true,
  "transaction": {
    "TransactionType": "Payment",
    "Account": "rwLCaTrEfgq8SFmz5A8TQALoyfX79EkfPf",
    "Destination": "r3GNZ9D5hzzecocx5pi6dNmrQ342VpKxUh",
    "Amount": "1",
    "DestinationTag": 752904,
    "Fee": "11",
    "hash": "CC4BE0643E9FD8D1BB896A0B0464590A06834FD5A5022A5C5B8B124D19F6F276"
  },
  "meta": {
    "TransactionResult": "tesSUCCESS",
    "delivered_amount": "1",
    "...": "..."
  }
}
Enter fullscreen mode Exit fullscreen mode

This server sends the API v1 layout, with the transaction under transaction; in API v2 the same object is called tx_json.

That payment moved 1 drop, a millionth of an XRP. Most of the stream is small payments, offers and other activity, so filter before you print anything.

3. Read delivered_amount, not Amount

Amount is what the sender asked for. With a partial payment, the ledger can deliver much less, so a payment can claim a million XRP in Amount and deliver almost nothing. meta.delivered_amount is what actually arrived. XRP arrives as a string of drops; a token arrives as an object with currency, issuer and value.

4. The whale alert

Save this as whale.mjs:

// XRP whale alert: Node 22 or later, no packages.
const MIN = Number(process.argv[2] ?? 1_000_000); // smallest payment to show, in XRP

// Names for the 200 largest XRP accounts (exchanges, Ripple, ...) from the xrpl.to API, no key needed
const res = await fetch('https://api.xrpl.to/v1/holders/list/84e5efeb89c4eae8f68188982dc290d8?limit=200');
if (!res.ok) throw new Error(`xrpl.to answered ${res.status}: try again in a minute`);
const names = new Map((await res.json()).richList.filter((h) => h.name).map((h) => [h.account, h.name]));
const who = (a) => names.get(a) ?? a;

// Every validated transaction, live, from a public server
const ws = new WebSocket('wss://s1.xrpl.stream');
ws.onopen = () => ws.send(JSON.stringify({ command: 'subscribe', streams: ['transactions'] }));
ws.onmessage = ({ data }) => {
  const m = JSON.parse(data);
  const tx = m.transaction;
  if (m.type !== 'transaction' || tx.TransactionType !== 'Payment' || m.engine_result !== 'tesSUCCESS') return;
  const delivered = m.meta.delivered_amount; // what arrived, not what Amount claims
  if (typeof delivered !== 'string') return;  // XRP is a string of drops; tokens are objects
  const xrp = Number(delivered) / 1e6;
  if (xrp >= MIN) console.log(`${xrp.toLocaleString('en-US')} XRP  ${who(tx.Account)} -> ${who(tx.Destination)}  https://xrpl.to/tx/${tx.hash}`);
};
Enter fullscreen mode Exit fullscreen mode

The names come from the xrpl.to API: one call returns the 200 largest XRP accounts, with labels for the exchanges, Ripple and other known wallets among them. That endpoint answers 5 calls a minute without a key, so the script makes one call at start. Every labelled wallet is on xrpl.to/known-wallets.

Request

node whale.mjs 250000
Enter fullscreen mode Exit fullscreen mode

Response

All the XRP payments of 250,000 XRP or more in 8 minutes on 22 November 2026:

2,000,000 XRP  Bithumb -> rw3fRcmn5PJyPKuvtAwHDSpEqoW2JKmKbu  https://xrpl.to/tx/D19655A4163D9518AD2B580D2A1DC78ACB71944F9E7EB7AB4F5EEC15C970E5E5
700,000 XRP  rGxYmmME93guyy4HuNv1bRf6gak8vGNN4B -> rGDreBvnHrX1get7na3J4oowN19ny4GzFn  https://xrpl.to/tx/00807ACC59C1A43A5A6694B8495B961B83E2BE790C2F7A5DB7F8B352961D34B7
Enter fullscreen mode Exit fullscreen mode

Each line links to the transaction on xrpl.to, which shows both accounts, their balances and their history.

5. Keep it running

  • A WebSocket can drop. Add ws.onclose = () => setTimeout(start, 1000) and wrap the connect and subscribe in start() to reconnect.
  • s1.xrpl.stream needs no key for light use; xrpl.stream has free keys with higher limits.
  • To watch only some accounts, subscribe with "accounts": ["r..."] instead of "streams": ["transactions"].

If you show data from api.xrpl.to in an app, put <a href="https://xrpl.to">Data by xrpl.to</a> on the same screen. The full API reference is at xrpl.to/docs.

Top comments (0)