# 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

<table><thead><tr><th width="142.60546875">Price Type</th><th>Description</th><th>Used For</th></tr></thead><tbody><tr><td><strong>Mark Price</strong></td><td>Price used for trade execution</td><td>TP/SL, Limit Orders, Stop Orders, PnL calculations</td></tr><tr><td><strong>Index Price</strong></td><td>Spot price, unaffected by derivatives skew</td><td><strong>Liquidations only</strong></td></tr></tbody></table>

#### How Prices Differ by Market Type

<table><thead><tr><th width="110.26171875">Type</th><th width="193.171875">Mark Price</th><th width="130.21875">Index Price</th><th>Examples</th></tr></thead><tbody><tr><td><strong>Core</strong></td><td>market (spot + skew)</td><td>spot</td><td>BTC, ETH (funding fees)</td></tr><tr><td><strong>Volatile</strong></td><td>futures</td><td>spot</td><td>Non-core crypto</td></tr><tr><td><strong>Regular</strong></td><td>spot</td><td>spot</td><td>Forex, stocks, commodities, non-core crypto w/o futures</td></tr></tbody></table>

* **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)**

```json
// Timestamp checkpoint
[1707580800000]

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

**v4 (New)**

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

<table><thead><tr><th width="121.4296875">Field</th><th width="146.0078125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>m</code></td><td><code>number[]</code></td><td>Mark prices as flat array <code>[pairIndex, price, ...]</code></td></tr><tr><td><code>i</code></td><td><code>number[]</code></td><td>Index prices as flat array <code>[pairIndex, price, ...]</code></td></tr><tr><td><code>t</code></td><td><code>number</code></td><td>Timestamp (milliseconds)</td></tr></tbody></table>

#### `/charts` Endpoint

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

**Before:**

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

**After:**

```json
{
  "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:

```typescript
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):**

```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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gains.trade/developer/integrators/guides/mark-+-index-introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.