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

{
  "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

# 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

{
  "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

# 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