Docs·TapeScript

Events

TapeScript callbacks — onTrade, onDepth, onBbo, onInterval, plus onOrder and onIceberg for each order on market-by-order venues — with trade sides and venue data.

A callback is a top-level function with a reserved name. TapeScript calls it when the matching market event occurs. Declare only the callbacks the script uses.

CallbackCalled onArguments
onTradeEach tradeprice, size, side, time
onDepthEach order-book level changeside, price, size, time
onBboA change of best bid / ask price or sizebid, bidSize, ask, askSize, time
onIntervalEach // @interval periodtime
onOrderEach change to a single order in the bookevent, id, side, price, size, time
onIcebergAn iceberg order detected, refilled or goneevent, id, side, price, shown, hidden, time

time is the event timestamp in milliseconds (exchange time). All callbacks receive the data of the symbol shown on the tick heatmap.

onTrade

JavaScript
function onTrade(price, size, side, time) {
  if (side === BUY) buys += size
  else if (side === SELL) sells += size
}
sideMeaning
BUYBuyer was the aggressor
SELLSeller was the aggressor
NONEThe venue does not report the aggressor

onDepth

JavaScript
function onDepth(side, price, size, time) {
  if (size === 0) log("level removed", side === BID ? "bid" : "ask", price)
}

Called for each level that was added, resized or removed. side is BID or ASK. size is the new size; 0 means the level was removed. To read the full book, use book.

onBbo

JavaScript
function onBbo(bid, bidSize, ask, askSize, time) {
  imbLine.add(time, (bidSize - askSize) / (bidSize + askSize))
}

Called when the best bid or ask price or size changes.

onInterval

JavaScript
// @interval 250ms

function onInterval(time) {
  if (vw.volume > 0) vwapLine.add(time, vw.value)
}

Called at the period set by @interval (50 ms to 60 s). Use it to add points to a line at a fixed rate or to expire data from a timeWindow.

onOrder

JavaScript
const pulled = timeWindow(10000)

function onOrder(event, id, side, price, size, time) {
  if (event === CANCEL && side === BID) pulled.add(time, size)
  if (event === RESET) pulled.clear()
}

Called for each change to one order, on venues that report every order with its id (market-by-order, for example CME futures through Rithmic). id is the exchange order id, a string. side is BID or ASK.

eventMeaningsize
ADDA new order rests in the bookOrder size
MODIFYThe order changed size or price, or moved to the back of its queueNew size
FILLPart of the order tradedSize traded
CANCELThe order was pulledSize removed
RESETThe book was rebuilt after a reconnect0

A fill is told apart from a pull by matching the trade to the order. When the trade arrives after the order shrank, you get MODIFY or CANCEL first and then a FILL for the same order.

On RESET, clear everything you track per order. The orders already resting when the script starts are not sent as ADD; read them with orders.

onIceberg

JavaScript
function onIceberg(event, id, side, price, shown, hidden, time) {
  if (event === DETECTED) marker(time, price, "ICE")
}
eventMeaning
DETECTEDAn order traded and refilled at the same price for the first time
REFILLEDThe same order refilled again
EXHAUSTEDThe order is gone

shown is the largest size the order displayed. hidden is the size it traded beyond that.

Venue data

Some venues do not report every type of data:

Missing dataEffect
Aggressor sideonTrade is called with side === NONE.
Order-book depthonDepth and onBbo are not called; book is empty.
Single orders (market-by-order)onOrder and onIceberg are not called; orders is empty.

If your Rithmic login has no market-by-order data for the symbol, the Console says so and the script restarts with venue.hasOrders === false.

Check with venue.hasAggressor, venue.hasDepth and venue.hasOrders:

JavaScript
function onTrade(price, size, side, time) {
  if (!venue.hasAggressor) return
  delta += side === BUY ? size : -size
}

History

A script with // @history first runs over the stored data of that period, then continues live without a gap or a repeat.

JavaScript
// @history 1h

function onTrade(price, size, side, time) {
  if (size >= 50) marker(time, price, "B " + size)
  if (!isHistory() && size >= 200) alert("Block " + size, { sound: "fill" })
}

During the replay:

  • onTrade, onDepth, onBbo and onInterval are called with the stored data, in market order. Book updates are sampled every 250 ms.
  • onOrder and onIceberg are not called; they start with live data.
  • isHistory() returns true. Alerts, sounds and voice are not played.
  • The Console shows when the replay starts and ends.

Where the history comes from

SourceContainsWhen
The desktop app's own recordingTrades and the order bookPeriods when the app was open, with the symbol picked in Data recording
The venue's trade historyTrades onlyPeriods with no recording, on venues that publish past trades

For a period with no recording, only onTrade is called and book is empty. Venue trade history is available for Binance USDⓈ-M futures and spot. Requests to the venue are rate-limited, so on a busy symbol it may reach back only a few minutes; the Console shows how much was replayed. Other venues replay the recording only.

Recording symbols

Recording is off by default. To turn it on:

  1. Open API Connect and select Rithmic.
  2. Click Recording settings.
  3. Turn on Record to disk, then add up to 6 products under Symbols to record (for example ES, NQ, GC).

The app records the front-month contract of each product, trades and order book, whenever it is open, with or without a chart on that symbol. In the same dialog you set the disk budget, how many days to keep, and clear the stored data. When the budget is reached, the oldest days are removed first.

Timing

  • Events arrive in market order.
  • now() returns the time of the latest event the script received.
  • When the chart's symbol or venue changes, the script restarts from its top-level code, with its history again.