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

# History Endpoints Migration

> Migration to the new trading history endpoints with cursor-based pagination (Dec 2025).

NOTE: The old endpoints were fully removed on December 1, 2025. Use the new endpoints below.

## 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

<table><thead><tr><th width="265.76171875">Old Endpoint</th><th>New Endpoint</th><th>Changes</th></tr></thead><tbody><tr><td><code>GET /trading-history-24h</code></td><td><code>GET /api/trading-history/24h?chainId=\{id}</code></td><td>Path prefix added, chainId support</td></tr></tbody></table>

**Migration:**

```diff theme={null}
- 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**

<table><thead><tr><th width="232.66796875">Old Endpoint</th><th width="287.69140625">New Endpoint</th><th>Changes</th></tr></thead><tbody><tr><td><code>GET /personal-trading-history-table/:address</code></td><td><code>GET /api/personal-trading-history/:address?chainId=X</code></td><td>Path renamed, cursor-based pagination, limits</td></tr></tbody></table>

**Migration:**

```diff theme={null}
- 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:**

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

```javascript theme={null}
// 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:**

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

**Response:**

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

```http theme={null}
POST /api/personal-trading-history/stats
Content-Type: application/json

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

**Response:**

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

```http theme={null}
POST /api/personal-trading-history/batch
Content-Type: application/json

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

**Response:**

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