History Endpoints Migration

NOTE: Old endpoints will be fully removed Mon Dec 1. Please migrate to new endpoints.

Backend Global API Migration Guide

Overview

The trading history endpoints have been migrated from backend-[network] service to the new backend-global endpoints with improved caching, pagination, and new statistics endpoints.

Base URL Change:

• Old: https://backend-[network].gains.trade

• New: https://backend-global.gains.trade

---

Endpoint Migration Map

24-Hour Trading History

Old Endpoint	New Endpoint	Changes
GET /trading-history-24h	GET /api/trading-history/24h?chainId={id}	Path prefix added, chainId support

Migration:

- GET https://backend-arbitrum.gains.trade/trading-history-24h
+ GET https://backend-global.gains.trade/api/trading-history/24h?chainId=42161

Response Format: Unchanged (returns array of trades)

---

Personal Trading History

Main History Endpoint

Old Endpoint	New Endpoint	Changes
GET /personal-trading-history-table/:address	GET /api/personal-trading-history/:address?chainId=X	Path renamed, cursor-based pagination, limits

Migration:

- GET https://backend.gains.trade/personal-trading-history-table/0x123...
+ GET https://backend-global.gains.trade/api/personal-trading-history/0x123...?chainId=42161&limit=50

Response Format:

{
  "data": [...],           // Array of trades (same as before)
  "pagination": {
    "hasMore": true,       // Whether more data available
    "nextCursor": 123456,  // Cursor for next page (null if no more)
    "limit": 50           // Limit used for this request, no higher than 200
  }
}

Pagination:

• Old: No offset

• New: Cursor-based (?cursor=123456)

To fetch next page:

// Old (offset-based)
const page1 = await fetch(
  "/personal-trading-history-table/0x123?offset=0&limit=50"
);
const page2 = await fetch(
  "/personal-trading-history-table/0x123?offset=50&limit=50"
);

// New (cursor-based)
const page1 = await fetch("/api/personal-trading-history/0x123?limit=50");
const { data, pagination } = await page1.json();

if (pagination.hasMore) {
  const page2 = await fetch(
    `/api/personal-trading-history/0x123?cursor=${pagination.nextCursor}&limit=50`
  );
}

Query Parameters:

• chainId (required): Chain ID

• cursor (optional): Pagination cursor (omit for first page)

• limit (optional): Max trades per request (default: 50, max: 1000)

• startDate (optional): ISO 8601 date filter

• endDate (optional): ISO 8601 date filter

• pair (optional): Trading pair filter

• action (optional): Action type filter

---

Statistics Endpoint (NEW)

New endpoint for trader statistics:

GET /api/personal-trading-history/:address/stats?chainId={id}

Response:

{
  "totalVolume": 123456.78,
  "totalTrades": 42,
  "winRate": 65.5,
  "thirtyDayVolume": 12345.67
}

Use case: Get all-time stats without fetching full trade history.

---

Batch Statistics Endpoint (NEW)

New endpoint for batched trader statistics:

POST /api/personal-trading-history/stats
Content-Type: application/json

{
  "addresses": ["0x123...", "0x456..."],
  "chainId": 42161
}

Response:

{
  "0x123...": {
      "totalVolume": 123456.78,
      "totalTrades": 42,
      "winRate": 65.5,
      "thirtyDayVolume": 12345.67
  },
  "0x456...": {
      "totalVolume": 67890.12,
      "totalTrades": 12,
      "winRate": 40.13,
      "thirtyDayVolume": 2345.67
  }
}

Use case: Get all-time stats without fetching full trade history.

---

Batch Trading History Endpoint (NEW)

New endpoint for fetching multiple addresses:

POST /api/personal-trading-history/batch
Content-Type: application/json

{
  "addresses": ["0x123...", "0x456..."],
  "chainId": 42161,
  "limit": 50,
  "cursors": {"0x123...": 123, "0x456...": null}
}

Response:

{
  "0x123...": {
    "data": [...],
    "pagination": { "hasMore": true, "nextCursor": 123, "limit": 50 }
  },
  "0x456...": {
    "data": [...],
    "pagination": { "hasMore": false, "nextCursor": null, "limit": 50 }
  }
}

---

Deprecated Endpoints

⚠️ DO NOT USE

Endpoint	Status	Replacement
GET /personal-trading-history/:address	DEPRECATED	Use /api/personal-trading-history/:address
GET /personal-trading-history-table/:address	DEPRECATED	Use /api/personal-trading-history/:address
GET /trading-history-24h	DEPRECATED	Use /api/trading-history/24h

Note: The old /personal-trading-history/:address (without -table) returned a flat array and is now deprecated. Use the new cursor-based endpoint instead.

---

Migration Checklist

• Update base URL from backend.gains.trade → backend-global.gains.trade

• Add /api prefix to all endpoints

• Rename /personal-trading-history-table → /personal-trading-history

• Add cursor pagination

• Update response parsing to handle { data, pagination } structure

• Use /stats endpoint if only statistics are needed

---

Support

For questions or issues with migration, please contact the Gains Network development team.