# 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.). > **🔒 Affiliate-code gating:** Only include events for addresses attributed to DexPal's affiliate code. If none of the provided addresses are DexPal-attributed, 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 ` | ### 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`. --- # 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.dexpal.io/for-partners/endpoints/user-history.md?ask= ``` 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.