Realtime Wallet Balances

Why This Endpoint?

Every wallet application needs to answer a simple question: "What tokens does this wallet hold, and what are they worth?"

The Vybe token balance endpoint provides:

Complete list of all SPL tokens in a wallet
Accurate USD valuations from vetted market prices
24-hour and 7-day portfolio change tracking
Filtering to remove dust and unverified tokens
Sorting by value, amount, or other criteria

Unlike raw RPC calls that just return token amounts, Vybe enriches every balance with current prices, token metadata, and change metrics—everything you need to display a polished portfolio view.

Endpoint

GET /wallets/{ownerAddress}/token-balance

Parameters

Parameter	Type	Description
`ownerAddress`	string	Wallet public key (required)
`sortByAsc`	string	Sort ascending: `amount`, `value`
`sortByDesc`	string	Sort descending: `amount`, `value`
`limit`	number	Results per page (max 1000)
`page`	number	Page number for pagination
`minAssetValue`	string	Filter: minimum USD value
`maxAssetValue`	string	Filter: maximum USD value
`onlyVerified`	boolean	Only return verified tokens

Example Request

curl "https://api.vybenetwork.com/wallets/7Tar8QZTrRPwoGY5Ke9Vfwf6CmpBfekrNofERxgReza/token-balance?sortByDesc=value&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "ownerAddress": "7Tar8QZTrRPwoGY5Ke9Vfwf6CmpBfekrNofERxgReza",
  "totalTokenValueUsd": "15234.56",
  "totalTokenValueSol": "82.15",
  "totalTokenValueUsd1dChange": "+234.12",
  "totalTokenValueUsd7dChange": "+1205.43",
  "data": [
    {
      "mintAddress": "So11111111111111111111111111111111111111112",
      "symbol": "SOL",
      "name": "Wrapped SOL",
      "amount": "50.5",
      "decimals": 9,
      "priceUsd": "185.42",
      "valueUsd": "9363.71",
      "priceUsd1dChange": "+2.3",
      "logoUrl": "https://..."
    },
    {
      "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "amount": "5000.00",
      "decimals": 6,
      "priceUsd": "1.00",
      "valueUsd": "5000.00",
      "priceUsd1dChange": "0.0",
      "logoUrl": "https://..."
    }
  ]
}

Response Fields Explained

Field	Description
`totalTokenValueUsd`	Sum of all token values in USD
`totalTokenValueSol`	Sum of all token values in SOL
`totalTokenValueUsd1dChange`	Portfolio change in last 24 hours
`totalTokenValueUsd7dChange`	Portfolio change in last 7 days
`data[].amount`	Human-readable token amount (decimals applied)
`data[].valueUsd`	Current USD value of this holding
`data[].priceUsd1dChange`	Token price change (24h)

Common Use Cases

Use Case	Implementation
Portfolio Tracker	Display all holdings sorted by value
Trading Dashboard	Check available balance before swap
Rebalancing Bot	Compare current vs target allocations
Tax Reporting	Export holdings at specific timestamps
Airdrop Eligibility	Verify user holds required tokens
Wallet Verification	Confirm ownership for token-gated access

Best Practices

Filter Out Dust

Use minAssetValue=1 to exclude worthless tokens that clutter the UI:

?minAssetValue=1&sortByDesc=value

Production Apps: Verified Only

Use onlyVerified=true to filter out scam tokens and unverified mints:

?onlyVerified=true&sortByDesc=value

Combine with History

For portfolio charts, pair this with the balance history endpoint:

const [current, history] = await Promise.all([
  fetch(`/wallets/${addr}/token-balance`),
  fetch(`/wallets/${addr}/token-balance-ts?days=30`)
]);

Portfolio Display Example

async function renderPortfolio(walletAddress) {
  const response = await fetch(
    `https://api.vybenetwork.com/wallets/${walletAddress}/token-balance?sortByDesc=value&onlyVerified=true`,
    { headers: { "X-API-Key": API_KEY } }
  );
  const portfolio = await response.json();
  
  return {
    totalValue: `$${parseFloat(portfolio.totalTokenValueUsd).toLocaleString()}`,
    change24h: portfolio.totalTokenValueUsd1dChange,
    holdings: portfolio.data.map(token => ({
      symbol: token.symbol,
      amount: parseFloat(token.amount).toLocaleString(),
      value: `$${parseFloat(token.valueUsd).toLocaleString()}`,
      change: token.priceUsd1dChange,
      logo: token.logoUrl
    }))
  };
}

Related Endpoints

Balance History - Track portfolio value over 30 days
NFT Balances - Add NFTs to the portfolio view
DeFi Positions - Include LP and staking positions
Batch Queries - Query multiple wallets at once