# Users

### Get User Balances

Retrieve all users holding a specific xToken with their aggregated balance data across multiple DeFi protocols.

#### Endpoint

```
GET /sdk/tokenized/:symbol/users
```

#### Parameters

**Path Parameters**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `symbol`  | string | Yes      | The xToken symbol (e.g., "xHYPE") |

**Query Parameters**

| Parameter   | Type   | Default | Description                                      |
| ----------- | ------ | ------- | ------------------------------------------------ |
| `offset`    | number | 0       | Number of results to skip                        |
| `limit`     | number | 100     | Results per page (max: 5000)                     |
| `timestamp` | number | -       | Unix timestamp (seconds) for historical balances |

#### Response

```json
{
  "users": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "totalBalance": "1250.50",
      "vaultBalances": [
        { "shares": "500.00", "chainId": 999 }
      ],
      "pendlePT": [
        { "shares": "100.00", "chainId": 999, "marketAddress": "0x..." }
      ],
      "pendleYT": [
        { "shares": "50.00", "chainId": 999, "marketAddress": "0x..." }
      ],
      "pendleLP": [
        { "shares": "150.00", "chainId": 999, "marketAddress": "0x..." }
      ],
      "dexBalances": [
        {
          "shares": "350.00",
          "chainId": 999,
          "poolAddress": "0x...",
          "tokenId": "123",
          "fee": 500,
          "tickLower": -887220,
          "tickUpper": 887220,
          "dexName": "HyperSwap",
          "poolName": "xHYPE/USDC 0.05%",
          "totalValueLockedUSD": "1250000.00"
        }
      ],
      "moneyMarketBalances": [
        { "shares": "100.00", "chainId": 999, "pairAddress": "0x..." }
      ]
    }
  ],
  "offset": 0,
  "limit": 100,
  "totalUsers": 1500,
  "timestamp": 1699900000
}
```

> **Note**: The `timestamp` field is only present in the response when requested via query parameter.

#### Response Fields

**User Object**

| Field                 | Type   | Description                                 |
| --------------------- | ------ | ------------------------------------------- |
| `address`             | string | User's wallet address                       |
| `totalBalance`        | string | Sum of all balance sources (human-readable) |
| `vaultBalances`       | array  | Direct xToken holdings per chain            |
| `pendlePT`            | array  | Pendle Principal Token positions            |
| `pendleYT`            | array  | Pendle Yield Token positions                |
| `pendleLP`            | array  | Pendle LP positions                         |
| `dexBalances`         | array  | DEX LP positions containing xTokens         |
| `moneyMarketBalances` | array  | Collateral deposited in lending markets     |

**Vault Balance Object**

| Field     | Type   | Description           |
| --------- | ------ | --------------------- |
| `shares`  | string | xToken balance        |
| `chainId` | number | Chain ID of the vault |

**Pendle Balance Objects (PT, YT, LP)**

| Field           | Type   | Description                    |
| --------------- | ------ | ------------------------------ |
| `shares`        | string | xToken equivalent amount       |
| `chainId`       | number | Chain ID                       |
| `marketAddress` | string | Pendle market contract address |

**DEX Balance Object**

| Field                 | Type   | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `shares`              | string | xToken amount in the LP position        |
| `chainId`             | number | Chain ID                                |
| `poolAddress`         | string | Pool contract address                   |
| `tokenId`             | string | NFT token ID of the LP position         |
| `fee`                 | number | Pool fee tier (e.g., 500 = 0.05%)       |
| `tickLower`           | number | Lower tick boundary of the position     |
| `tickUpper`           | number | Upper tick boundary of the position     |
| `dexName`             | string | DEX name (e.g., "HyperSwap", "Uniswap") |
| `poolName`            | string | Human-readable pool name                |
| `totalValueLockedUSD` | string | Pool TVL in USD                         |

**Money Markets Balance Object**

| Field         | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| `shares`      | string | Collateral amount (xToken equivalent) |
| `chainId`     | number | Chain ID                              |
| `pairAddress` | string | Lending pair contract address         |

#### Example Requests

```bash
# Basic request
curl "https://api.liminal.money/sdk/tokenized/xHYPE/users?limit=50&offset=0"

# Historical query
curl "https://api.liminal.money/sdk/tokenized/xHYPE/users?timestamp=1699900000"

# Pagination
curl "https://api.liminal.money/sdk/tokenized/xHYPE/users?limit=100&offset=100"
```

***

### Get LST Holdings

Retrieve each user's proportional share of the xToken LST (Liquid Staking Token) holdings based on their xToken balance relative to all users.

#### Endpoint

```
GET /sdk/tokenized/:symbol/lst-holdings
```

#### Parameters

**Path Parameters**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `symbol`  | string | Yes      | The xToken symbol (e.g., "xHYPE") |

**Query Parameters**

| Parameter   | Type   | Default | Description                                      |
| ----------- | ------ | ------- | ------------------------------------------------ |
| `offset`    | number | 0       | Number of results to skip                        |
| `limit`     | number | 100     | Results per page (max: 5000)                     |
| `timestamp` | number | -       | Unix timestamp (seconds) for historical balances |

#### Response

```json
{
  "users": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "totalBalance": "1000.00",
      "shareOfVault": "5.000000%",
      "weightedLstHolding": "500.00"
    },
    {
      "address": "0xabcdef1234567890abcdef1234567890abcdef12",
      "totalBalance": "500.00",
      "shareOfVault": "2.500000%",
      "weightedLstHolding": "250.00"
    }
  ],
  "offset": 0,
  "limit": 100,
  "totalUsers": 1500
}
```

#### Response Fields

| Field                | Type   | Description                                                |
| -------------------- | ------ | ---------------------------------------------------------- |
| `address`            | string | User's wallet address                                      |
| `totalBalance`       | string | User's total xToken balance (human-readable)               |
| `shareOfVault`       | string | User's percentage share of total vault (e.g., "5.000000%") |
| `weightedLstHolding` | string | User's proportional LST amount (human-readable)            |

#### Example Requests

```bash
# Basic request
curl "https://api.liminal.money/sdk/tokenized/xHYPE/lst-holdings"

# With pagination
curl "https://api.liminal.money/sdk/tokenized/xHYPE/lst-holdings?limit=50&offset=100"

# Historical query
curl "https://api.liminal.money/sdk/tokenized/xHYPE/lst-holdings?timestamp=1699900000"
```

***

### Important Notes

* All `shares` and `totalBalance` values are in **human-readable format** (divided by 1e18)
* Results are **cached for 60 seconds**
* DEX positions calculate the xToken amount based on current pool price and position range
* Pendle positions are scaled to match actual SY (Standardized Yield) balance on-chain

***

### Errors

| Code | Description                            |
| ---- | -------------------------------------- |
| 400  | Missing `symbol` parameter             |
| 404  | xToken not found or LST not configured |
| 500  | Internal server error                  |


---

# 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.liminal.money/tokenized/developers/sdk/users.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.