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:

Name
Type
Description
Required

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 needed

  • For 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.

PreviousToken List

Last updated