GET /v1/balances/:walletAddress

Return the SPL token balances of a wallet, filtered to mints the API tracks. Useful for swap UIs that want to sort the token picker by what the user actually holds, or for portfolio tools.

Backed by getTokenAccountsByOwner against our Triton RPC for both the SPL Token and Token-2022 programs in parallel. Results are coalesced and cached server-side for 5 seconds per wallet to prevent thundering-herd RPC cost when multiple tabs / clients hit the same wallet.

Request

GET /v1/balances/:walletAddress
X-API-Key: YOUR_API_KEY

Path parameters

Field	Type	Description
walletAddress	string	Base58 wallet pubkey (32-44 chars)

Example

curl https://api.venum.dev/v1/balances/7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs \
  -H 'x-api-key: YOUR_API_KEY'

Response

200 OK

{
  "wallet": "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs",
  "balances": [
    {
      "mint": "So11111111111111111111111111111111111111112",
      "symbol": "SOL",
      "decimals": 9,
      "amount": "12450000000",
      "uiAmount": 12.45
    },
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "decimals": 6,
      "amount": "2105000000",
      "uiAmount": 2105
    }
  ],
  "fetchedAt": 1733587200000
}

Balance object

Field	Type	Description
mint	string	Base58 mint address
symbol	string	Tracked symbol (e.g. "SOL", "USDC")
decimals	number	Token decimals
amount	string	Raw amount in smallest units, as a base-10 string
uiAmount	number	Human-readable amount (amount / 10^decimals)

Notes:

• SOL is always returned (lamports → SOL conversion), even when the balance is zero.
• SPL token accounts with a zero balance are filtered out to keep responses compact (wallets often own many empty ATAs).
• Mints not in our tracked token list are filtered out as well — this is a product API, not a generic indexer.
• fetchedAt is the UNIX millisecond timestamp at which the underlying RPC call returned. Subsequent identical requests within 5 s reuse this value.

Errors

Status	Description
400	Invalid wallet address (not a valid pubkey)
401	Missing or invalid API key
429	Rate limit exceeded
502	Upstream RPC error

Auth

Requires API key.

Rate Limit

Tier limits (per minute):

Tier	Limit
anonymous	0
free	10
starter	60
pro	300
internal	∞