# 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

<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
- 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
- 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
{
  "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
// 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
GET /api/personal-trading-history/:address/stats?chainId={id}
```

**Response:**

```json
{
  "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
POST /api/personal-trading-history/stats
Content-Type: application/json

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

**Response:**

```json
{
  "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
POST /api/personal-trading-history/batch
Content-Type: application/json

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

**Response:**

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


---

# 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/history-endpoints-migration.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.