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.
| Callback | Called on | Arguments |
|---|---|---|
onTrade | Each trade | price, size, side, time |
onDepth | Each order-book level change | side, price, size, time |
onBbo | A change of best bid / ask price or size | bid, bidSize, ask, askSize, time |
onInterval | Each // @interval period | time |
onOrder | Each change to a single order in the book | event, id, side, price, size, time |
onIceberg | An iceberg order detected, refilled or gone | event, 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
function onTrade(price, size, side, time) {
if (side === BUY) buys += size
else if (side === SELL) sells += size
}
side | Meaning |
|---|---|
BUY | Buyer was the aggressor |
SELL | Seller was the aggressor |
NONE | The venue does not report the aggressor |
onDepth
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
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
// @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
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.
event | Meaning | size |
|---|---|---|
ADD | A new order rests in the book | Order size |
MODIFY | The order changed size or price, or moved to the back of its queue | New size |
FILL | Part of the order traded | Size traded |
CANCEL | The order was pulled | Size removed |
RESET | The book was rebuilt after a reconnect | 0 |
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
function onIceberg(event, id, side, price, shown, hidden, time) {
if (event === DETECTED) marker(time, price, "ICE")
}
event | Meaning |
|---|---|
DETECTED | An order traded and refilled at the same price for the first time |
REFILLED | The same order refilled again |
EXHAUSTED | The 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 data | Effect |
|---|---|
| Aggressor side | onTrade is called with side === NONE. |
| Order-book depth | onDepth 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:
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.
// @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,onBboandonIntervalare called with the stored data, in market order. Book updates are sampled every 250 ms.onOrderandonIcebergare not called; they start with live data.isHistory()returnstrue. Alerts, sounds and voice are not played.- The Console shows when the replay starts and ends.
Where the history comes from
| Source | Contains | When |
|---|---|---|
| The desktop app's own recording | Trades and the order book | Periods when the app was open, with the symbol picked in Data recording |
| The venue's trade history | Trades only | Periods 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:
- Open API Connect and select Rithmic.
- Click Recording settings.
- 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.