# Trades (/scripting/sources/trades)



The `trades` source sends each live market trade to a script. Select the exchange and provider in the source selector:

```bash
--source btc@trades@bulkf
--source btc@trades@hyperliquidf
--source btc@trades@binancef@mmt
```

`btc@trades@bulkf`, `btc@trades@hyperliquidf`, `tsla@trades@hyperliquidf-xyz`, and `sndk@trades@hyperliquidf-io` use standalone exchange feeds. `btc@trades@binancef@mmt` uses Binance USD-M perpetual trades through MMT.

## Script Setup [#script-setup]

Declare the base source kind in the manifest:

```js
export const script = {
  name: 'trade-monitor',
  version: '1',
  sources: ['trades'],
  lookback: 100,
  params: {},
}
```

Then configure the exact live source:

```bash
mlab script run ./scripts/trade-monitor.js \
  --source btc@trades@bulkf
```

Read that same exact selector inside the script:

```js
export function onData(ctx, input, history) {
  const trades = history.source('btc@trades@bulkf')
  const latest = history.source('btc@trades@bulkf', 0)

  if (!latest) return
}
```

Without an index, `history.source('btc@trades@bulkf')` returns the buffered trades from oldest to newest. Index `0` returns the newest trade.

## Record Shape [#record-shape]

Each record contains only price and size:

```js
{
  price: 1927.5,
  size: 0.25,
}
```

The source selector already identifies the symbol, exchange, and provider, so those fields are not repeated in each record. Trade timestamps and aggressor side remain internal.

Market Lab still uses internal trade direction when it builds trade-derived candles and volume delta.

## Live Only [#live-only]

`trades` is a live-only source. A live script receives one `onData` event for every trade received through the real-time WebSocket feed.

Raw trades are not available to the script backtester. A backtest that configures a `trades` source stops with a clear live-only source error.

Use historical candles in backtests:

```js
export function onData(ctx, input, history) {
  const candles = history.source('btc@candles@bulkf')
  const latestCandle = history.source('btc@candles@bulkf', 0)

  if (!latestCandle) return
}
```

```bash
mlab script backtest ./scripts/candle-strategy.js \
  --from <UTC_DATETIME> \
  --to <UTC_DATETIME> \
  --source btc@candles@bulkf:timeframe=60
```

## Shared MMT Stream [#shared-mmt-stream]

When one script requests both MMT trades and trade-derived candles for the same market, Market Lab reuses one underlying trade subscription. It does not open a second MMT trade feed.