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

# User LP Holdings

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

> **Collection endpoint:** Return LP, vault, and staking positions 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 LP/vault/staking positions, 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.