# Realtime Wallet Balances

Get real-time SPL token balances for any Solana wallet with accurate USD valuations from vetted markets. This is the foundation of any portfolio tracker, wallet app, or trading dashboard

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

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

***

## Example Response

```json
{
  "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:

```bash
?minAssetValue=1&sortByDesc=value
```

### Production Apps: Verified Only

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

```bash
?onlyVerified=true&sortByDesc=value
```

### Combine with History

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

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

***

## Portfolio Display Example

```javascript
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](./balance-history.md) - Track portfolio value over 30 days
* [NFT Balances](./nft-balances.md) - Add NFTs to the portfolio view
* [DeFi Positions](./defi-positions.md) - Include LP and staking positions
* [Batch Queries](./batch-queries.md) - Query multiple wallets at once