History, then live

Trades, transfers and an account’s activity each have two methods:

.query answers once, with a page of history.
.subscribe sends history and then live events, with nothing missed or repeated between them.

A live list

Subscribe with history set to how many past events to show (up to 200). The reply has them newest first, and each push after it has a block’s new events, oldest first:

Using the client from the Quickstart:

let latestId = 0;

const { result } = await api.subscribe(
  'trades.subscribe',
  {
    fields: ['id', 'timestamp_millis', 'trader', 'side', 'amount', 'usd_value'],
    token: 'wrap.near',
    history: 50,
  },
  (push) => {
    if (push.end) throw new Error(`Subscription ended: ${push.end.message}`);
    const rows = push.rows ?? [];
    latestId = Math.max(latestId, ...rows.map((row) => Number(row[0])));
    addTrades(rows); // oldest first
  },
);

latestId = result.latest_id;
addTrades(result.rows.toReversed()); // history comes newest first
// After a reconnect, subscribe with `after_id: latestId` instead of `history`

Older pages

When there’s more history than history asked for, the reply has next_cursor. Pass it as cursor to the matching .query method for the page before, and keep going with each page’s next_cursor until it’s null:

{ "id": 2, "method": "trades.query", "params": { "fields": ["id", "side", "usd_value"], "token": "wrap.near", "limit": 200, "cursor": "1792003517185090582:6860366" } }

Use the same filters as the subscription. .query also takes after_millis (inclusive) and before_millis (exclusive) to limit history to a time range.

After a reconnect

Subscribe again with after_id (for trades and transfers) instead of history. The reply has every event after that one, oldest first, and pushes carry on from there:

Set after_id to the newest id you have, or the reply’s latest_id if that’s newer. latest_id is the newest event the reply accounts for, matching or not, so it can be ahead of your newest row.
For activity.subscribe, use after set to the last of the last reply or push you got. Activity mixes trades, transfers and transactions, so it can’t use a single id.
More than 10,000 events after it is an error, too_far_behind: start over with history.

With neither history nor after_id, a subscription only sends events from now on.

Filters

Trades can be filtered by token, the other token, trader, side and size, and transfers by token, sender, receiver and amount. See Trades, Transfers and Activity for every filter.

parent follows the tokens directly under an account instead of one token, like every token launched on a platform. It’s resolved when the request is made, so tokens created after that aren’t included.