> For the complete documentation index, see [llms.txt](https://docs.dexpal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dexpal.io/for-partners/endpoints/user-history.md).

# User History

Returns a paginated history of trading events for the provided wallet addresses within a given time range. Each item represents a discrete event (position opened, size increased, position closed, liquidation, etc.).

> **Collection endpoint:** Return history for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. DexPal enforces any user-facing visibility restrictions after collection. If none of the provided addresses have history, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec.md).

## Overview

|                |                |
| -------------- | -------------- |
| **Method**     | GET            |
| **Auth**       | Bearer API key |
| **Rate limit** | 120 req/min    |

## Request

### Query Parameters

| Param    | Type    | Required | Description                                        |
| -------- | ------- | -------- | -------------------------------------------------- |
| `addr`   | string  | yes      | Comma-separated list of wallet addresses to query. |
| `from`   | ISO8601 | yes      | Start of the time range (inclusive).               |
| `to`     | ISO8601 | yes      | End of the time range (inclusive).                 |
| `limit`  | integer | no       | Items per page. Default `100`, max `500`.          |
| `offset` | integer | no       | Items to skip. Default `0`.                        |

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | yes      | `Bearer <api_key>` |

### Example Request

```
GET /dexpal/v1/users/history?addr=0x1a2b...,0x9c3d...&from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z&limit=100&offset=0
```

## Response

Returns a paginated `data` array of trade event objects, ordered by `createdAt` descending (most recent first).

### Fields — History Event Object

| Field                | Type    | Required | Description                                                                                                                         |
| -------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `positionId`         | string  | yes      | Links this event back to a position. Same format as [`positions`](/for-partners/endpoints/user-positions.md): `exchange:wallet:id`. |
| `address`            | string  | yes      | The wallet address associated with this event.                                                                                      |
| `exchange`           | string  | yes      | DEX slug where the event occurred.                                                                                                  |
| `category`           | enum    | yes      | Type of event. See values below.                                                                                                    |
| `side`               | enum    | yes      | Position direction at the time of the event. `long` or `short`.                                                                     |
| `baseAsset`          | string  | yes      | Base currency symbol.                                                                                                               |
| `quoteAsset`         | string  | yes      | Quote currency symbol.                                                                                                              |
| `assetType`          | string  | yes      | Asset category. See [AssetObject](/for-partners/schemas/asset-object.md) for valid values.                                          |
| `price`              | number  | yes      | Asset mark price at the time of the event, in quote currency.                                                                       |
| `avgEntryPrice`      | number  | yes      | Average entry price for the position at the time of the event.                                                                      |
| `positionSizeUsd`    | number  | yes      | Position size at the time of the event, in USD.                                                                                     |
| `collateralUsd`      | number  | no       | Collateral posted at the time of the event, in USD.                                                                                 |
| `leverage`           | number  | no       | Leverage used at the time of the event.                                                                                             |
| `realizedPnl`        | number  | no       | Realized profit/loss in USD. Present only on `closePosition`, `liquidation`, `takeProfit`, and `stopLoss` events.                   |
| `feeBorrowingUsd`    | number  | no       | Borrow fees attributed to this event, in USD.                                                                                       |
| `feeFundingUsd`      | number  | no       | Funding fees attributed to this event, in USD.                                                                                      |
| `feeTradingUsd`      | number  | no       | Trading fees attributed to this event, in USD.                                                                                      |
| `feeNetworkUsd`      | number  | no       | Gas/network fees attributed to this event, in USD.                                                                                  |
| `role`               | enum    | no       | User's role in the trade. `maker` or `taker`. Present only on `openPosition` events.                                                |
| `chainId`            | integer | no       | Wagmi/viem chain ID of the network where the event occurred.                                                                        |
| `txHash`             | string  | no       | On-chain transaction hash. Allows the user to verify the event on a block explorer.                                                 |
| `createdAt`          | ISO8601 | yes      | Timestamp when the event occurred.                                                                                                  |
| `updatedAt`          | ISO8601 | no       | Timestamp of the last update to this event record.                                                                                  |
| `feeRateBps`         | number  | no       | Effective fee rate for this event in basis points.                                                                                  |
| `liquidationType`    | string  | no       | Liquidation scope. `partial`, `full`, or `backstop`. Only set when `category` is `liquidation`.                                     |
| `remainingSize`      | number  | no       | Remaining position size in USD after a partial liquidation.                                                                         |
| `realizedPnlGross`   | number  | no       | Realized PnL before fees. `realizedPnl` is always net of fees.                                                                      |
| `collateralDeltaUsd` | number  | no       | Collateral change in USD. Positive = added, negative = removed. Only set on `collateralAdd` / `collateralRemove` events.            |
| `accountId`          | string  | no       | Subaccount or portfolio ID.                                                                                                         |

### `category` Values

| Value              | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `openPosition`     | A new position was opened.                            |
| `increaseSize`     | An existing position's size was increased.            |
| `decreaseSize`     | An existing position's size was partially reduced.    |
| `closePosition`    | A position was fully closed by the user.              |
| `liquidation`      | A position was liquidated by the protocol.            |
| `takeProfit`       | A take profit trigger order was executed.             |
| `stopLoss`         | A stop loss trigger order was executed.               |
| `adl`              | Position was auto-deleveraged against a counterparty. |
| `fundingPayment`   | A periodic funding payment was applied.               |
| `collateralAdd`    | Collateral was added to the position.                 |
| `collateralRemove` | Collateral was withdrawn from the position.           |

## Example Response

```json
{
  "success": true,
  "data": [
    {
      "positionId": "vela:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:85",
      "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "exchange": "vela",
      "category": "openPosition",
      "side": "long",
      "baseAsset": "WIF",
      "quoteAsset": "USD",
      "assetType": "crypto",
      "price": 1.506775,
      "avgEntryPrice": 1.506775,
      "positionSizeUsd": 90.0,
      "collateralUsd": 20.0,
      "leverage": 4.5,
      "realizedPnl": null,
      "feeBorrowingUsd": 0.0,
      "feeFundingUsd": 0.0,
      "feeTradingUsd": 0.04,
      "feeNetworkUsd": 0.01,
      "role": "taker",
      "chainId": 42161,
      "txHash": "0x9a9305605ee27d2cff45122479306271459b06b88d6bbed244d0a6cdf00eb390",
      "createdAt": "2024-09-06T22:52:39Z",
      "updatedAt": "2024-09-06T22:52:39Z"
    },
    {
      "positionId": "vela:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:85",
      "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "exchange": "vela",
      "category": "closePosition",
      "side": "long",
      "baseAsset": "WIF",
      "quoteAsset": "USD",
      "assetType": "crypto",
      "price": 1.92,
      "avgEntryPrice": 1.506775,
      "positionSizeUsd": 90.0,
      "collateralUsd": 20.0,
      "leverage": 4.5,
      "realizedPnl": 24.86,
      "feeBorrowingUsd": 0.03,
      "feeFundingUsd": 0.01,
      "feeTradingUsd": 0.04,
      "feeNetworkUsd": 0.01,
      "chainId": 42161,
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "createdAt": "2024-09-09T17:43:57Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 432,
    "hasMore": true
  }
}
```

## Error Responses

| Status | Error                                       | When                      |
| ------ | ------------------------------------------- | ------------------------- |
| `400`  | `"Missing required parameter: addr"`        | `addr` absent             |
| `400`  | `"Missing required parameter: from"`        | `from` or `to` absent     |
| `400`  | `"Invalid date format for parameter: from"` | Not valid ISO8601         |
| `400`  | `"Parameter 'from' must be before 'to'"`    | Inverted range            |
| `401`  | `"Invalid or missing API key"`              | Bad or absent auth header |
| `500`  | `"Internal server error"`                   | Unexpected failure        |

## Notes

* Results are ordered by `createdAt` descending (most recent first).
* `realizedPnl` should only be present on closing events (`closePosition`, `liquidation`, `takeProfit`, `stopLoss`). Omit or return `null` for all other categories.
* `role` should only be present on `openPosition` events.
* All fee fields on a given event represent fees attributed to that event only, not cumulative position totals.
* If a position was partially closed via `decreaseSize` and then fully closed, each action is a separate event with the same `positionId`.