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
| 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 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
// Timestamp checkpoint
[1707580800000]
// Price update (flat array: [pairIndex, price, pairIndex, price, ...])
[0, 45000.50, 1, 2500.25, 2, 150.75]
{
"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.
/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.
{
"opens": [45000.50, 2500.25, ...],
"highs": [45100.00, 2510.00, ...],
"lows": [44900.00, 2490.00, ...],
"closes": [45050.00, 2505.00, ...],
"time": 1707580800
}
{
"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 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. 