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.

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

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