# User LP Holdings

Returns the LP, vault, and staking positions held by the provided addresses, along with any accrued pending rewards.

> **🔒 Affiliate-code gating:** Only include LP/vault/staking positions 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/lp-holdings?addr=0x1a2b...,0x9c3d...
```

## Response

Returns a `data` array where each item represents one earn position for one address. A single address may appear multiple times across different mechanisms or networks.

### Fields — LP Holding Object

| Field               | Type    | Required | Description                                                                                                                                                                   |
| ------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address`           | string  | yes      | The wallet address holding this position.                                                                                                                                     |
| `mechanismName`     | string  | yes      | Human-readable name of the earn mechanism e.g. `"wBTC/USDC Liquidity Pool"`, `"GNS Staking"`. Matches `name` from the [`earn`](/for-partners/endpoints/dex-earn.md) endpoint. |
| `type`              | enum    | yes      | Mechanism category. `staking`, `vault`, `lp`, or `lending`.                                                                                                                   |
| `network`           | string  | yes      | Chain slug where this position is held e.g. `"arbitrum"`.                                                                                                                     |
| `exchange`          | string  | yes      | DEX slug e.g. `"gmx"`, `"gains"`.                                                                                                                                             |
| `amount`            | number  | yes      | Deposited or staked amount in token units.                                                                                                                                    |
| `amountUsd`         | number  | yes      | USD value of the position at current price.                                                                                                                                   |
| `autoCompounding`   | boolean | yes      | Whether rewards are automatically reinvested into the position.                                                                                                               |
| `pendingRewardsUsd` | number  | no       | Accrued but unclaimed rewards in USD. `0` if no pending rewards.                                                                                                              |
| `dexLink`           | string  | no       | Deep link to this earn position on the DEX.                                                                                                                                   |

## Example Response

```json
{
  "success": true,
  "data": [
    {
      "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "mechanismName": "GNS Staking",
      "type": "staking",
      "network": "arbitrum",
      "exchange": "gains",
      "amount": 1250.0,
      "amountUsd": 2412.50,
      "autoCompounding": false,
      "pendingRewardsUsd": 12.50,
      "dexLink": "https://gains.trade/staking"
    },
    {
      "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "mechanismName": "DAI Vault",
      "type": "vault",
      "network": "arbitrum",
      "exchange": "gains",
      "amount": 500.0,
      "amountUsd": 500.0,
      "autoCompounding": true,
      "pendingRewardsUsd": 0,
      "dexLink": "https://gains.trade/vaults"
    },
    {
      "address": "0x9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
      "mechanismName": "wBTC/USDC Liquidity Pool",
      "type": "lp",
      "network": "arbitrum",
      "exchange": "gmx",
      "amount": 0.0056,
      "amountUsd": 378.24,
      "autoCompounding": false,
      "pendingRewardsUsd": 4.20,
      "dexLink": "https://app.gmx.io/#/earn"
    }
  ]
}
```

## 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 earn mechanism per address per network. If a user has staked in the same pool on two networks, return two separate items.
* Zero-balance positions may be omitted.
* `pendingRewardsUsd` represents rewards that have accrued but not yet been claimed or compounded. For `autoCompounding: true` mechanisms, this is typically `0`.
* `amount` is in the deposit token units — for LP positions this is LP token units, for staking this is the staked token units.
* `mechanismName` should match the `name` field returned by the [`earn`](/for-partners/endpoints/dex-earn.md) endpoint so DexPal can correlate user holdings with mechanism metadata.


---

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