> For the complete documentation index, see [llms.txt](https://docs.liminal.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.liminal.money/tokenized/developers/sdk/users.md).

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