Fomo API logoFOMO APIDOCS

Documentation

IntroductionAuthenticationQuickstartGETHealthGETLeaderboardGETResolve traderGETTrader balancesGETTrader followersGETTrader followingGETTrader spotlightGETTrader swapsWSTrade stream

[ API reference ]

Trader balances

Returns a trader's token holdings, portfolio value, per-chain totals and live perpetual position information.

GET/api/users/{handle}/balances

This endpoint requires an API key using X-API-Key or Bearer authorization.

01

Request

curl

curl "https://getfomoapi.fun/api/users/{handle}/balances" \
  -H "X-API-Key: YOUR_API_KEY"
02

Parameters

handlepathstringPublic Fomo trader handle. The leading @ character is optional.
03

Response fields

balancesarrayToken holdings across supported chains.
balances[].tokenobjectToken symbol, address and network information.
balances[].token.symbolstringToken symbol.
balances[].token.addressstringToken contract address.
balances[].token.networkIdstring | numberToken network identifier.
balances[].chainstringFriendly blockchain name.
balances[].amountnumberNumber of tokens held.
balances[].priceUsdnumberCurrent token price in USD.
balances[].valueUsdnumberCurrent position value in USD.
balances[].change24hnumber24-hour price change percentage.
totalValueUsdnumberCombined value of all token holdings in USD.
byChainobjectHolding count and portfolio value grouped by chain.
livePerpPnlnumber | nullCurrent live perpetual position PnL.
hyperliquidPerpsobject | nullCurrent Hyperliquid perpetual swaps.
04

JSON response

A successful request returns the following response structure.

response.json

{
  "balances": [
    {
      "token": {
        "symbol": "SOL",
        "address": "So11111111111111111111111111111111111111112",
        "networkId": 1399811149
      },
      "chain": "solana",
      "amount": 125.42,
      "priceUsd": 196.25,
      "valueUsd": 24611.18,
      "change24h": 2.84
    }
  ],
  "totalValueUsd": 24611.18,
  "byChain": {
    "solana": {
      "holdings": 1,
      "valueUsd": 24611.18
    }
  },
  "livePerpPnl": 421.75,
  "hyperliquidPerps": null
}

Rate limits and retry

Pro keys allow 5 requests per second. On a 429 response, wait for the Retry-After value before retrying.