# 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).

> **🔒 Affiliate-code gating:** Only include holdings 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. |

### 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.


---

# 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-holdings.md?ask=<question>
```

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.