Add Bitget V3 normalized mappings

Author: thaaddeus

ADD_NEW_EXCHANGE.md

@@ -48,7 +48,7 @@ Mapper decisions to make explicit:
 
 Normalized type semantics:
 
-- **Trades** — `side` is liquidity taker side: `buy` means the aggressor bought, `sell` means the aggressor sold. Invert maker-side flags when needed. Skip off-book maintenance events such as insurance fund or ADL unless the product contract explicitly requires them.
+- **Trades** — `side` is liquidity taker side: `buy` means the aggressor bought, `sell` means the aggressor sold. Invert maker-side flags when needed. Skip off-book maintenance events such as insurance fund or ADL unless the product contract explicitly requires them. If a trade channel uses `snapshot` followed by `update`, map only `update`; the initial `snapshot` is recent-trade backfill and must have a test that emits nothing to avoid duplicate or stale trades after reconnect. Map trade `snapshot` only when the exchange sends trades exclusively as snapshots and there is no incremental update variant.
 - **Book changes** — `book_change` is L2 market-by-price data. `isSnapshot=true` means consumers discard prior book state. `isSnapshot=false` means consumers apply absolute price-level amounts to the current book. `amount=0` removes the level.
 - **Book tickers** — `book_ticker` comes from native top-of-book or BBO feeds. It is not `quotes`, which are computed from reconstructed L2 books.
 - **Derivative tickers** — keep `lastPrice`, `openInterest`, `indexPrice`, `markPrice`, funding fields, and predicted funding fields aligned with exchange meaning. `fundingTimestamp` is the next funding event timestamp.

src/consts.ts

@@ -514,8 +514,8 @@ const KUCOIN_FUTURES_CHANNELS = [
   'contractMarket/snapshot'
 ]
 
-const BITGET_CHANNELS = ['trade', 'books1', 'books15']
-const BITGET_FUTURES_CHANNELS = ['trade', 'books1', 'books15', 'ticker']
+const BITGET_CHANNELS = ['trade', 'publicTrade', 'books1', 'books15', 'books']
+const BITGET_FUTURES_CHANNELS = ['trade', 'publicTrade', 'books1', 'books15', 'books', 'ticker', 'liquidation']
 const COINBASE_INTERNATIONAL_CHANNELS = ['INSTRUMENTS', 'MATCH', 'FUNDING', 'RISK', 'LEVEL1', 'LEVEL2', 'CANDLES_ONE_MINUTE']
 
 const HYPERLIQUID_CHANNELS = ['l2Book', 'trades', 'activeAssetCtx', 'activeSpotAssetCtx', 'bbo']

src/mappers/bitget.ts

@@ -1,5 +1,5 @@
-import { upperCaseSymbols } from '../handy.ts'
-import { BookChange, BookTicker, DerivativeTicker, Exchange, Trade } from '../types.ts'
+import { asNumberIfValid, upperCaseSymbols } from '../handy.ts'
+import { BookChange, BookTicker, DerivativeTicker, Exchange, Liquidation, Trade } from '../types.ts'
 import { Mapper, PendingTickerInfoHelper } from './mapper.ts'
 
 export class BitgetTradesMapper implements Mapper<'bitget' | 'bitget-futures', Trade> {
@@ -155,6 +155,182 @@ export class BitgetDerivativeTickerMapper implements Mapper<'bitget-futures', De
   }
 }
 
+export class BitgetV3TradesMapper implements Mapper<'bitget' | 'bitget-futures', Trade> {
+  constructor(private readonly _exchange: Exchange) {}
+
+  canHandle(message: BitgetV3TradeMessage) {
+    return message.arg.topic === 'publicTrade' && message.action === 'update'
+  }
+
+  getFilters(symbols?: string[]) {
+    symbols = upperCaseSymbols(symbols)
+
+    return [
+      {
+        channel: 'publicTrade',
+        symbols
+      } as const
+    ]
+  }
+
+  *map(message: BitgetV3TradeMessage, localTimestamp: Date): IterableIterator<Trade> {
+    for (const trade of message.data) {
+      yield {
+        type: 'trade',
+        symbol: message.arg.symbol,
+        exchange: this._exchange,
+        id: trade.i,
+        price: Number(trade.p),
+        amount: Number(trade.v),
+        side: trade.S === 'buy' ? 'buy' : 'sell',
+        timestamp: new Date(Number(trade.T)),
+        localTimestamp
+      }
+    }
+  }
+}
+
+export class BitgetV3BookChangeMapper implements Mapper<'bitget' | 'bitget-futures', BookChange> {
+  constructor(private readonly _exchange: Exchange) {}
+
+  canHandle(message: BitgetV3OrderbookMessage) {
+    return message.arg.topic === 'books' && (message.action === 'snapshot' || message.action === 'update')
+  }
+
+  getFilters(symbols?: string[]) {
+    symbols = upperCaseSymbols(symbols)
+
+    return [
+      {
+        channel: 'books',
+        symbols
+      } as const
+    ]
+  }
+
+  *map(message: BitgetV3OrderbookMessage, localTimestamp: Date): IterableIterator<BookChange> {
+    for (const orderbookData of message.data) {
+      yield {
+        type: 'book_change',
+        symbol: message.arg.symbol,
+        exchange: this._exchange,
+        isSnapshot: message.action === 'snapshot',
+        bids: orderbookData.b.map(mapPriceLevel),
+        asks: orderbookData.a.map(mapPriceLevel),
+        timestamp: new Date(Number(orderbookData.ts)),
+        localTimestamp
+      }
+    }
+  }
+}
+
+export class BitgetV3BookTickerMapper implements Mapper<'bitget' | 'bitget-futures', BookTicker> {
+  constructor(private readonly _exchange: Exchange) {}
+
+  canHandle(message: BitgetV3BBoMessage) {
+    return message.arg.topic === 'books1' && message.action === 'snapshot'
+  }
+
+  getFilters(symbols?: string[]) {
+    symbols = upperCaseSymbols(symbols)
+
+    return [
+      {
+        channel: 'books1',
+        symbols
+      } as const
+    ]
+  }
+
+  *map(message: BitgetV3BBoMessage, localTimestamp: Date): IterableIterator<BookTicker> {
+    for (const bboMessage of message.data) {
+      yield {
+        type: 'book_ticker',
+        symbol: message.arg.symbol,
+        exchange: this._exchange,
+        askAmount: bboMessage.a[0] ? asNumberIfValid(bboMessage.a[0][1]) : undefined,
+        askPrice: bboMessage.a[0] ? asNumberIfValid(bboMessage.a[0][0]) : undefined,
+        bidPrice: bboMessage.b[0] ? asNumberIfValid(bboMessage.b[0][0]) : undefined,
+        bidAmount: bboMessage.b[0] ? asNumberIfValid(bboMessage.b[0][1]) : undefined,
+        timestamp: new Date(Number(bboMessage.ts)),
+        localTimestamp
+      }
+    }
+  }
+}
+
+export class BitgetV3DerivativeTickerMapper implements Mapper<'bitget-futures', DerivativeTicker> {
+  private readonly pendingTickerInfoHelper = new PendingTickerInfoHelper()
+
+  canHandle(message: BitgetV3TickerMessage) {
+    return message.arg.topic === 'ticker' && (message.action === 'snapshot' || message.action === 'update')
+  }
+
+  getFilters(symbols?: string[]) {
+    symbols = upperCaseSymbols(symbols)
+
+    return [
+      {
+        channel: 'ticker',
+        symbols
+      } as const
+    ]
+  }
+
+  *map(message: BitgetV3TickerMessage, localTimestamp: Date): IterableIterator<DerivativeTicker> {
+    for (const tickerMessage of message.data) {
+      const pendingTickerInfo = this.pendingTickerInfoHelper.getPendingTickerInfo(message.arg.symbol, 'bitget-futures')
+
+      pendingTickerInfo.updateIndexPrice(Number(tickerMessage.indexPrice))
+      pendingTickerInfo.updateMarkPrice(Number(tickerMessage.markPrice))
+      pendingTickerInfo.updateOpenInterest(Number(tickerMessage.openInterest))
+      pendingTickerInfo.updateLastPrice(Number(tickerMessage.lastPrice))
+      pendingTickerInfo.updateTimestamp(new Date(Number(message.ts)))
+
+      if (tickerMessage.nextFundingTime !== '' && tickerMessage.nextFundingTime !== '0') {
+        pendingTickerInfo.updateFundingTimestamp(new Date(Number(tickerMessage.nextFundingTime)))
+        pendingTickerInfo.updateFundingRate(Number(tickerMessage.fundingRate))
+      }
+
+      if (pendingTickerInfo.hasChanged()) {
+        yield pendingTickerInfo.getSnapshot(localTimestamp)
+      }
+    }
+  }
+}
+
+export class BitgetV3LiquidationsMapper implements Mapper<'bitget-futures', Liquidation> {
+  canHandle(message: BitgetV3LiquidationMessage) {
+    return message.arg.topic === 'liquidation' && message.action === 'update'
+  }
+
+  getFilters() {
+    return [
+      {
+        channel: 'liquidation',
+        symbols: undefined
+      } as const
+    ]
+  }
+
+  *map(message: BitgetV3LiquidationMessage, localTimestamp: Date): IterableIterator<Liquidation> {
+    for (const liquidation of message.data) {
+      yield {
+        type: 'liquidation',
+        symbol: liquidation.symbol,
+        exchange: 'bitget-futures',
+        id: undefined,
+        price: Number(liquidation.price),
+        amount: Number(liquidation.amount),
+        // Bitget side is position side, normalized side is the liquidated aggressor side.
+        side: liquidation.side === 'buy' ? 'sell' : 'buy',
+        timestamp: new Date(Number(liquidation.ts)),
+        localTimestamp
+      }
+    }
+  }
+}
+
 type BitgetTradeMessage = {
   action: 'update'
   arg: { instType: 'SPOT'; channel: 'trade'; instId: 'OPUSDT' }
@@ -214,3 +390,62 @@ type BitgetTickerMessage = {
   ]
   ts: 1730332823220
 }
+
+type BitgetV3TradeMessage = {
+  action: 'snapshot' | 'update'
+  arg: { instType: string; topic: 'publicTrade'; symbol: string }
+  data: { i: string; p: string; v: string; S: 'buy' | 'sell'; T: string; L: string; isRPI?: string }[]
+  ts: number
+}
+
+type BitgetV3BookLevel = [string, string]
+
+type BitgetV3OrderbookMessage = {
+  action: 'snapshot' | 'update'
+  arg: { instType: string; topic: 'books'; symbol: string }
+  data: { a: BitgetV3BookLevel[]; b: BitgetV3BookLevel[]; checksum: number; seq: number; pseq: number; ts: string }[]
+  ts: number
+}
+
+type BitgetV3BBoMessage = {
+  action: 'snapshot'
+  arg: { instType: string; topic: 'books1'; symbol: string }
+  data: { a: BitgetV3BookLevel[]; b: BitgetV3BookLevel[]; checksum: number; seq: number; pseq: number; ts: string }[]
+  ts: number
+}
+
+type BitgetV3TickerMessage = {
+  action: 'snapshot' | 'update'
+  arg: { instType: string; topic: 'ticker'; symbol: string }
+  data: [
+    {
+      highPrice24h: string
+      lowPrice24h: string
+      openPrice24h: string
+      lastPrice: string
+      turnover24h: string
+      volume24h: string
+      bid1Price: string
+      ask1Price: string
+      bid1Size: string
+      ask1Size: string
+      price24hPcnt: string
+      indexPrice: string
+      markPrice: string
+      fundingRate: string
+      openInterest: string
+      deliveryTime: string
+      deliveryStartTime: string
+      deliveryStatus: string
+      nextFundingTime: string
+    }
+  ]
+  ts: number
+}
+
+type BitgetV3LiquidationMessage = {
+  action: 'update'
+  arg: { instType: string; topic: 'liquidation' }
+  data: { symbol: string; side: 'buy' | 'sell'; price: string; amount: string; ts: string }[]
+  ts: number
+}

src/mappers/index.ts

@@ -27,7 +27,17 @@ import {
   BitfinexTradesMapper
 } from './bitfinex.ts'
 import { BitflyerBookChangeMapper, bitflyerBookTickerMapper, bitflyerTradesMapper } from './bitflyer.ts'
-import { BitgetBookChangeMapper, BitgetBookTickerMapper, BitgetDerivativeTickerMapper, BitgetTradesMapper } from './bitget.ts'
+import {
+  BitgetBookChangeMapper,
+  BitgetBookTickerMapper,
+  BitgetDerivativeTickerMapper,
+  BitgetTradesMapper,
+  BitgetV3BookChangeMapper,
+  BitgetV3BookTickerMapper,
+  BitgetV3DerivativeTickerMapper,
+  BitgetV3LiquidationsMapper,
+  BitgetV3TradesMapper
+} from './bitget.ts'
 import {
   BitmexBookChangeMapper,
   BitmexDerivativeTickerMapper,
@@ -208,6 +218,12 @@ const shouldUseBybitAllLiquidationFeed = (localTimestamp: Date) => {
   return isRealTime(localTimestamp) || localTimestamp.valueOf() >= BYBIT_V5_API_ALL_LIQUIDATION_SUPPORT_DATE.valueOf()
 }
 
+const BITGET_V3_API_SWITCH_DATE = new Date('2026-04-28T00:00:00.000Z')
+
+const shouldUseBitgetV3Mappers = (localTimestamp: Date) => {
+  return isRealTime(localTimestamp) || localTimestamp.valueOf() >= BITGET_V3_API_SWITCH_DATE.valueOf()
+}
+
 const OKCOIN_V5_API_SWITCH_DATE = new Date('2023-04-27T00:00:00.000Z')
 const shouldUseOkcoinV5Mappers = (localTimestamp: Date) => {
   return isRealTime(localTimestamp) || localTimestamp.valueOf() >= OKCOIN_V5_API_SWITCH_DATE.valueOf()
@@ -320,8 +336,10 @@ const tradesMappers = {
       ? new BinanceEuropeanOptionsTradesMapperV2()
       : new BinanceEuropeanOptionsTradesMapper(),
   'okex-spreads': () => new OkexSpreadsTradesMapper(),
-  bitget: () => new BitgetTradesMapper('bitget'),
-  'bitget-futures': () => new BitgetTradesMapper('bitget-futures'),
+  bitget: (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp) ? new BitgetV3TradesMapper('bitget') : new BitgetTradesMapper('bitget'),
+  'bitget-futures': (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp) ? new BitgetV3TradesMapper('bitget-futures') : new BitgetTradesMapper('bitget-futures'),
   'coinbase-international': () => coinbaseInternationalTradesMapper,
   hyperliquid: () => new HyperliquidTradesMapper(),
   lighter: () => new LighterTradesMapper()
@@ -416,8 +434,12 @@ const bookChangeMappers = {
       ? new BinanceEuropeanOptionsBookChangeMapperV2()
       : new BinanceEuropeanOptionsBookChangeMapper(),
   'okex-spreads': () => new OkexSpreadsBookChangeMapper(),
-  bitget: () => new BitgetBookChangeMapper('bitget'),
-  'bitget-futures': () => new BitgetBookChangeMapper('bitget-futures'),
+  bitget: (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp) ? new BitgetV3BookChangeMapper('bitget') : new BitgetBookChangeMapper('bitget'),
+  'bitget-futures': (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp)
+      ? new BitgetV3BookChangeMapper('bitget-futures')
+      : new BitgetBookChangeMapper('bitget-futures'),
   'coinbase-international': () => new CoinbaseInternationalBookChangMapper(),
   hyperliquid: () => new HyperliquidBookChangeMapper(),
   lighter: () => new LighterBookChangeMapper()
@@ -454,7 +476,8 @@ const derivativeTickersMappers = {
   'crypto-com': () => new CryptoComDerivativeTickerMapper('crypto-com'),
   'woo-x': () => new WooxDerivativeTickerMapper(),
   'kucoin-futures': () => new KucoinFuturesDerivativeTickerMapper(),
-  'bitget-futures': () => new BitgetDerivativeTickerMapper(),
+  'bitget-futures': (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp) ? new BitgetV3DerivativeTickerMapper() : new BitgetDerivativeTickerMapper(),
   'coinbase-international': () => new CoinbaseInternationalDerivativeTickerMapper(),
   hyperliquid: () => new HyperliquidDerivativeTickerMapper(),
   lighter: () => new LighterDerivativeTickerMapper()
@@ -496,7 +519,8 @@ const liquidationsMappers = {
       ? new OkexV5LiquidationsMapper('okex-futures')
       : new OkexLiquidationsMapper('okex-futures', 'futures'),
   'okex-swap': (localTimestamp: Date) =>
-    shouldUseOkexV5Mappers(localTimestamp) ? new OkexV5LiquidationsMapper('okex-swap') : new OkexLiquidationsMapper('okex-swap', 'swap')
+    shouldUseOkexV5Mappers(localTimestamp) ? new OkexV5LiquidationsMapper('okex-swap') : new OkexLiquidationsMapper('okex-swap', 'swap'),
+  'bitget-futures': () => new BitgetV3LiquidationsMapper()
 }
 
 const bookTickersMappers = {
@@ -556,8 +580,12 @@ const bookTickersMappers = {
   'gate-io': () => new GateIOV4BookTickerMapper('gate-io'),
   'okex-spreads': () => new OkexSpreadsBookTickerMapper(),
   'kucoin-futures': () => new KucoinFuturesBookTickerMapper(),
-  bitget: () => new BitgetBookTickerMapper('bitget'),
-  'bitget-futures': () => new BitgetBookTickerMapper('bitget-futures'),
+  bitget: (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp) ? new BitgetV3BookTickerMapper('bitget') : new BitgetBookTickerMapper('bitget'),
+  'bitget-futures': (localTimestamp: Date) =>
+    shouldUseBitgetV3Mappers(localTimestamp)
+      ? new BitgetV3BookTickerMapper('bitget-futures')
+      : new BitgetBookTickerMapper('bitget-futures'),
   'coinbase-international': () => coinbaseInternationalBookTickerMapper,
   hyperliquid: () => new HyperliquidBookTickerMapper(),
   lighter: () => new LighterBookTickerMapper(),