User Holdings

Returns wallet and DEX account balances for the provided addresses. Covers both on-chain token balances and funds deposited into a DEX account (for DEXes that require account deposits).

Collection endpoint: Return holdings for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. If none of the provided addresses have holdings, 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.

Headers

Header	Required	Description
Authorization	yes	Bearer <api_key>

Example Request

GET /dexpal/v1/users/holdings?addr=0x1a2b...,0x9c3d...

Response

Returns a data array where each item represents one asset holding for one address. A single address may appear multiple times for different assets or networks.

Fields — Holding Object

Field	Type	Required	Description
address	string	yes	The wallet address that holds this balance.
asset	string	yes	Token symbol e.g. "BTC", "USDC", "ETH".
assetType	string	yes	Asset category e.g. "crypto". See AssetObject for valid values.
network	string	yes	Chain slug where this balance is held e.g. "arbitrum", "base".
exchange	string	no	null for on-chain wallet balances. DEX slug (e.g. "gmx") for funds deposited into a DEX account.
amount	number	yes	Raw token amount held.
amountUsd	number	yes	USD value of the holding at current price (amount × priceUsd).
priceUsd	number	yes	Current price of the asset in USD at the time of the response.

Example Response

{
  "success": true,
  "data": [
    {
      "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "asset": "BTC",
      "assetType": "crypto",
      "network": "arbitrum",
      "exchange": null,
      "amount": 0.0056,
      "amountUsd": 378.24,
      "priceUsd": 67543.21
    },
    {
      "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "asset": "ETH",
      "assetType": "crypto",
      "network": "arbitrum",
      "exchange": null,
      "amount": 1.25,
      "amountUsd": 4320.98,
      "priceUsd": 3456.78
    },
    {
      "address": "0x9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
      "asset": "USDC",
      "assetType": "crypto",
      "network": "arbitrum",
      "exchange": "gmx",
      "amount": 349.27,
      "amountUsd": 349.27,
      "priceUsd": 1.0
    }
  ]
}

Error Responses

Status	Error	When
400	"Missing required parameter: addr"	addr absent
401	"Invalid or missing API key"	Bad or absent auth header
500	"Internal server error"	Unexpected failure

Notes

• Return one item per asset per network per address. If an address holds ETH on both Arbitrum and Base, return two separate items.

• Zero balances may be omitted.

• exchange: null indicates a standard on-chain wallet balance. exchange: "gmx" (or similar) indicates funds deposited into a DEX's internal account system, separate from the wallet.

• amountUsd must equal amount × priceUsd at the time of the response. Do not use stale prices.

• Only return holdings relevant to this DEX's supported networks and assets. Do not return balances from unrelated chains.