> 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-holdings.md).

# 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](/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. |

### 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-partners/schemas/asset-object.md) 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

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