> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gains.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Mark + Index Introduction

> How the v4 pricing API separates mark prices from index prices, and how to migrate from v3.

**tl;dr**: v3 continues to work. No immediate breaking changes. However, since **Feb 16, 2025**, the v4 pricing API separates mark prices (TP/SL, limits, PnL) from index prices (liquidations) and is the recommended format. 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

Since **February 16, 2025**, Gains provides a v4 format that separates **mark prices** from **index prices** to support more advanced market structures and align with industry norms.

### 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 Gains 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 theme={null}
// Timestamp checkpoint
[1707580800000]

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

**v4 (New)**

```json theme={null}
{
  "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.

<Info>
  `/charts` returns the current OHLC snapshot for each pair. It is not a historical OHLCV candles API. The response does not include volume, interval, `from`, or `to` parameters.
</Info>

**Before:**

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

**After:**

```json theme={null}
{
  "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 theme={null}
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 theme={null}
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 became the recommended format; 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.