Mark + Index Introduction

tl;dr: v3 continues to work. No immediate breaking changes. However, starting Feb 16, 2025, the new v4 pricing API separates mark prices (TP/SL, limits, PnL) from index prices (liquidations). Action required only if you perform liquidation calculations on volatile pairs (non-core crypto with futures feeds). Without updating, those calculations will use the wrong price.

Mark & Index Price Separation (v4 API)

Overview

Starting February 16, 2025 (tentative), gTrade introduces a new v4 format that separates mark prices from index prices to support more advanced market structures and align with industry norm.

What Changed

Price Type	Description	Used For
Mark Price	Price used for trade execution	TP/SL, Limit Orders, Stop Orders, PnL calculations
Index Price	Spot price, unaffected by derivatives skew	Liquidations only

How Prices Differ by Market Type

Type	Mark Price	Index Price	Examples
Core	market (spot + skew)	spot	BTC, ETH (funding fees)
Volatile	futures	spot	Non-core crypto
Regular	spot	spot	Forex, stocks, commodities, non-core crypto w/o futures

• Core: Crypto with funding fees. Mark includes skew adjustment (for now clients have to calculate).

• Volatile: Crypto with futures feeds available. Mark sourced from futures.

• Regular: All other markets. Spot price used for both mark and index.

For Core and Regular pairs, mark and index prices will be identical from gTrade endpoints. For Volatile pairs, they may differ significantly. Core will still need mark/market price calculated on the client.

---

API Changes

Connection

To use the v4 API, connect to the v4 endpoint:

# v3 (legacy)
wss://backend-pricing.eu.gains.trade/v3

# v4 (new)
wss://backend-pricing.eu.gains.trade/v4

Message Format

v3 (Legacy)

// Timestamp checkpoint
[1707580800000]

// Price update (flat array: [pairIndex, price, pairIndex, price, ...])
[0, 45000.50, 1, 2500.25, 2, 150.75]

v4 (New)

{
  "m": [0, 45000.50, 1, 2500.25, 2, 150.75],
  "i": [0, 44998.00, 1, 2499.80, 2, 150.75],
  "t": 1707580800000
}

Field	Type	Description
m	number[]	Mark prices as flat array [pairIndex, price, ...]
i	number[]	Index prices as flat array [pairIndex, price, ...]
t	number	Timestamp (milliseconds)

/charts Endpoint

The /charts snapshot endpoint now includes an additional indexPrices field alongside the existing OHLC data.

Before:

{
  "opens": [45000.50, 2500.25, ...],
  "highs": [45100.00, 2510.00, ...],
  "lows": [44900.00, 2490.00, ...],
  "closes": [45050.00, 2505.00, ...],
  "time": 1707580800
}

After:

{
  "opens": [45000.50, 2500.25, ...],
  "highs": [45100.00, 2510.00, ...],
  "lows": [44900.00, 2490.00, ...],
  "closes": [45050.00, 2505.00, ...],
  "indexPrices": [44998.00, 2499.80, ...],
  "time": 1707580800
}

opens, highs, lows, closes reflect mark prices (as before). indexPrices provides the latest index price per pair index.

---

SDK Changes

@gainsnetwork/sdk v1.8.3 introduces:

• corePairIndices — exported from constants, provides the list of core crypto pair indices (BTC, ETH, etc.)

• getMarketType(pairIndex) — returns the market classification (CORE, VOLATILE, or REGULAR) for a given pair index

These can be used to determine which price type applies to each pair:

import { corePairIndices, getMarketType, MARKET_TYPE } from '@gainsnetwork/sdk';

const marketType = getMarketType(pairIndex);

if (marketType === MARKET_TYPE.VOLATILE) {
  // Mark = futures, Index = spot — prices will differ
}

---

Migration Guide

Example (TypeScript):

socket.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  
  // Parse mark prices (for TP/SL/limits)
  const markPrices = new Map<number, number>();
  for (let i = 0; i < data.m.length; i += 2) {
    markPrices.set(data.m[i], data.m[i + 1]);
  }
  
  // Parse index prices (for liquidations)
  const indexPrices = new Map<number, number>();
  for (let i = 0; i < data.i.length; i += 2) {
    indexPrices.set(data.i[i], data.i[i + 1]);
  }
  
};

---

Timeline

Date	Event
Feb 16, 2025	v4 becomes recommended; index prices enabled for volatile pairs
TBD	v3 deprecation (will be announced separately)

---

Impact of Not Updating

If you continue using v3 or don't separate mark/index prices:

• Liquidation calculations will be incorrect for volatile pairs, as they will use mark price instead of index price

• TP/SL/Limit orders are unaffected (these use mark price, which v3 provides)

• Price display is unaffected for most use cases

Recommendation: Evaluate your integration's use of price data. If you perform liquidation-related calculations, prioritize this update. The impact depends on your exposure to volatile pairs (non core crypto pairs with separate futures markets).

---

Questions?

Contact the Gains Network team on Discord if you have questions about the migration.