Token Balances
Returns token balances for a specific wallet address. This endpoint is essential for building trading interfaces, portfolio management tools, and any application that needs to display or verify user token holdings.
Common Use Cases
Trading Interface Development:
Display available balances before users initiate swaps
Validate that users have sufficient tokens for their intended trades
Show portfolio composition across different tokens
Portfolio Management:
Build dashboards showing total portfolio value
Track balance changes over time
Calculate portfolio allocation percentages
DeFi Application Integration:
Verify token holdings before allowing participation in protocols
Display collateral available for lending/borrowing
Show stakable token balances in yield farming interfaces
Analytics & Monitoring:
Track large wallet movements for market analysis
Monitor liquidity provider positions
Build tools for wallet analysis and research
Endpoint: GET /tokens/balances
Parameters:
wallet
address
Address of the wallet to check balances for
Yes
limit
number
Maximum number of tokens to return
No
Parameter Details:
wallet: Must be a valid Ethereum-style address (0x followed by 40 hexadecimal characters)
limit: Useful for pagination or when you only need the top token holdings. If not specified, returns all tokens with non-zero balances
Example Requests:
# Get all token balances for a wallet
GET https://api.liqd.ag/tokens/balances?wallet=0x123456789abcdef123456789abcdef123456789
# Get only the top 10 token holdings
GET https://api.liqd.ag/tokens/balances?wallet=0x123456789abcdef123456789abcdef123456789&limit=10
# Check balances for a specific analysis
GET https://api.liqd.ag/tokens/balances?wallet=0x742d35Cc6645C0532d9E5f62E5D7b9d13B8A1aE
Example Response:
{
"success": true,
"data": {
"wallet": "0x123456789abcdef123456789abcdef123456789",
"tokens": [
{
"token": "Native HYPE",
"balance": "1000000000000000000",
"name": "HYPE",
"symbol": "HYPE",
"decimals": 18
},
{
"token": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
"balance": "500000000000000000",
"name": "Token One",
"symbol": "TOKEN1",
"decimals": 18
}
],
"count": 2,
"limitedCount": 2
}
}
Understanding Balance Data
Balance Representation:
balance: Raw balance in the token's smallest unit (wei for 18-decimal tokens)
decimals: Number of decimal places for the token (most tokens use 18)
To get human-readable balance:
balance / (10 ^ decimals)
Token Information:
token: Contract address for ERC-20 tokens, or "Native HYPE" for the native token
name: Full token name as specified in the token contract
symbol: Token ticker symbol (e.g., "USDC", "WETH")
Response Metadata:
count: Total number of tokens found for this wallet
limitedCount: Number of tokens returned (may be less than count if limit was applied)
Working with Balance Data
Converting to Human-Readable Format:
// Example: Convert wei to readable amount
const balance = "1000000000000000000"; // 1 ETH in wei
const decimals = 18;
const readableBalance = parseFloat(balance) / Math.pow(10, decimals);
console.log(readableBalance); // 1.0
Checking Sufficient Balance for Trades:
// Before allowing a swap, verify the user has enough tokens
const userBalance = parseFloat(tokenData.balance) / Math.pow(10, tokenData.decimals);
const tradeAmount = 100; // User wants to trade 100 tokens
if (userBalance >= tradeAmount) {
// Proceed with trade
} else {
// Show insufficient balance error
}
Practical Integration Tips
Caching Strategy: Token balances change with every transaction, but for UI purposes, you might cache balances for short periods (30-60 seconds) to reduce API calls while maintaining reasonable accuracy.
Error Handling: Always handle cases where:
The wallet address doesn't exist or has no transaction history
Network issues cause the API call to fail
The wallet has no token balances (empty portfolio)
Performance Considerations:
Use the
limit
parameter for initial loads, then fetch more data if neededFor trading interfaces, you might only need balances for specific tokens rather than the entire portfolio
Consider combining this endpoint with token list data to show additional token metadata
Integration Examples
Portfolio Value Calculation: Combine balance data with price feeds to calculate total portfolio value across all holdings.
Trading Interface: Use balance data to populate dropdown menus with available tokens and their amounts, preventing users from attempting trades they can't afford.
DeFi Protocol Integration: Verify collateral availability before allowing users to borrow against their holdings or participate in liquidity mining programs.
Last updated