CRIUS Docs
API status Get API key
Holders & wallets

Get wallet token balances on Robinhood Chain (balances API)

Get every token balance of a Robinhood Chain wallet (USDG, tokenized stocks, ETH) in USD in one call, one token's balances across wallets, and batch prices.

Updated 3 min read
Short answer

Call GET /v1/robinhood/wallet/{address}?min_value_usd=1 (Starter plan, 5 credits). It returns the ETH balance (native_balance, native_value_usd) and up to 200 holdings[], most valuable first, each with token.address, balance in whole tokens, value_usd, value_eth and price_confidence, read on-chain at meta.balances_block. For one token's balances across all wallets use /token/{address}/holders (Free plan); to revalue balances you already have, GET /v1/robinhood/prices?tokens=... (anonymous, up to 100 tokens).

GET /wallet/{address} GET /prices GET /token/{address}/holders

A wallet’s token balances are how much of each ERC-20 it holds right now, plus its native ETH. The Crius balances API answers that for any Robinhood Chain address in one call: it finds every token the wallet has ever received, reads the balances on-chain at one block, prices them in USD from on-chain pools and returns them most valuable first. You don’t need a token list or one balanceOf call per token. This page is about balances; for the same call’s profit and loss numbers, see wallet holdings and PnL.

Get a wallet’s balances in one call

Example Starter plan · 5 credits

A trader holding $49,722 of USDG and five tokenized stocks

What does 0x2a4d34cd09a36f59ae3bedc0880cd5da929321d7 hold on Robinhood Chain, and what is it worth? Hide anything under $1.

GET/v1/robinhood/wallet/0x2a4d34cd09a36f59ae3bedc0880cd5da929321d7?min_value_usd=1
curl "https://api.crius.sh/v1/robinhood/wallet/0x2a4d34cd09a36f59ae3bedc0880cd5da929321d7?min_value_usd=1" \
  -H "x-api-key: $CRIUS_API_KEY"
Real response 200 Captured Oct 28, 2026 · 143 lines (arrays trimmed) 
{
  "data": {
    "account_type": "eoa",
    "address": "0x2a4d34cd09a36f59ae3bedc0880cd5da929321d7",
    "delegate": null,
    "holdings": [
      {
        "balance": 49721.880472,
        "pnl": null,
        "price_confidence": "high",
        "token": {
          "address": "0x5fc5360d0400a0fd4f2af552add042d716f1d168",
          "logo": null,
          "symbol": "USDG"
        },
        "value_eth": 21.0906,
        "value_usd": 49721.9
      },
      {
        "balance": 18.405208788009058717,
        "pnl": null,
        "price_confidence": "high",
        "token": {
          "address": "0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec",
          "logo": null,
          "symbol": "NVDA"
        },
        "value_eth": 1.67342,
        "value_usd": 3945.15
      },
      {
        "balance": 4.10654992139340626,
        "pnl": null,
        "price_confidence": "high",
        "token": {
          "address": "0xd5f3879160bc7c32ebb4dc785f8a4f505888de68",
          "logo": null,
          "symbol": "QQQ"
        },
        "value_eth": 1.25568,
        "value_usd": 2960.33
      },
      {
        "balance": 8.496965059200292092,
        "pnl": null,
        "price_confidence": "high",
        "token": {
          "address": "0xb0992820e760d836549ba69bc7598b4af75dee03",
          "logo": null,
          "symbol": "ORCL"
        },
        "value_eth": 0.509659,
        "value_usd": 1201.54
      },
      {
        "balance": 6.004187798458070634,
        "pnl": null,
        "price_confidence": "high",
        "token": {
          "address": "0x5e81213613b6b86eab4c6c50d718d34359459786",
          "logo": null,
          "symbol": "TTWO"
        },
        "value_eth": 0.504464,
        "value_usd": 1189.29
      },
      {
        "balance": 1.117684815247203549,
        "pnl": {
          "avg_entry_usd": 126.473,
          "realized_usd": 147.475,
          "unrealized_usd": 721.987
        },
        "price_confidence": "high",
        "token": {
          "address": "0x117cc2133c37b721f49de2a7a74833232b3b4c0c",
          "logo": null,
          "symbol": "SPY"
        },
        "value_eth": 0.366205,
        "value_usd": 863.344
      }
    ],
    "holdings_truncated": false,
    "holdings_value_usd": 70914,
    "is_contract": false,
    "label": null,
    "native_balance": 17.143712569865815681,
    "native_value_usd": 40417,
    "pnl": {
      "avg_hold_time_s": 20739,
      "best_trade": {
        "logo": "https://api.crius.sh/v1/robinhood/logo/0x448168b7c3736fb55c552dce72d5f1f5b30d77cb.png?size=128",
        "pnl_usd": 2326.69,
        "symbol": "Suited",
        "token": "0x448168b7c3736fb55c552dce72d5f1f5b30d77cb"
      },
      "gas_scope": "all transactions sent by the wallet in the window",
      "gas_spent_usd": 147.202,
      "realized_usd": 73090.6,
      "tokens_traded": 2067,
      "tokens_with_known_cost": 2052,
      "total_usd": 75466.3,
      "trades": 15076,
      "unrealized_usd": 2375.68,
      "volume_usd": 2801387,
      "win_rate_pct": 42.3002,
      "window": "30d",
      "worst_trade": {
        "logo": "https://api.crius.sh/v1/robinhood/logo/0x90e8fa19ae1a01431da01c6f80b3bc5cebb19438.png?size=128",
        "pnl_usd": -428.531,
        "symbol": "TMF",
        "token": "0x90e8fa19ae1a01431da01c6f80b3bc5cebb19438"
      }
    },
    "profile": {
      "first_seen_block": 91379092,
      "first_seen_ts": 1792286196200,
      "fresh": false,
      "funded_by": {
        "address": "0x07ae8551be970cb1cca11dd7a11f47ae82e70e67",
        "amount_eth": 20.297518745318700439,
        "block": 54422474,
        "label": null,
        "ts": 1788540817400
      },
      "history": "complete",
      "tags": [],
      "tx_count": 170001,
      "wallet_age_days": 10.9215
    }
  },
  "meta": {
    "balances_block": 100452982,
    "block": 100452982,
    "block_age_ms": 993,
    "block_ts": 1793229813000,
    "chain": "robinhood",
    "finalized_block": 100442370,
    "lag_ms": 53,
    "safe_block": 100446224
  }
}

What this tells you

  • native_balance: 17.143712569865815681 ETH, worth native_value_usd: 40417. ETH is never in holdings[]: add it yourself for a total.
  • The largest holding is USDG (0x5fc5360d0400a0fd4f2af552add042d716f1d168, the real one): balance: 49721.880472, value_usd: 49721.9. Its value_eth: 21.0906 is the same value expressed in ETH.
  • Then five tokenized stocks, each with price_confidence: "high": 18.405208788009058717 NVDA ($3,945.15), 4.10654992139340626 QQQ ($2,960.33), 8.496965059200292092 ORCL ($1,201.54), 6.004187798458070634 TTWO ($1,189.29) and 1.117684815247203549 SPY ($863.344). Balances keep full precision, so fractional stock tokens are exact.
  • holdings_value_usd: 70914 totals every holding worth $1 or more. The six rows shown add up to about $59,882, so the rest is in smaller holdings further down the list. With native_value_usd, the wallet is worth about $111,331.
  • holdings_truncated: false: every token the wallet touched was priced.
  • meta.balances_block: 100452982: the ETH and token balances were all read at that block, so they are consistent with each other.
Wallet profile reference Data looks wrong? Report it
Example Starter plan · 5 credits

A wallet whose only tokens are lookalikes

CHARGE's creator (0x3ac82d45ff9e4963cefbc3f74dbe293f34c927ca) shows two USDG balances. Are they real?

GET/v1/robinhood/wallet/0x3ac82d45ff9e4963cefbc3f74dbe293f34c927ca
curl "https://api.crius.sh/v1/robinhood/wallet/0x3ac82d45ff9e4963cefbc3f74dbe293f34c927ca" \
  -H "x-api-key: $CRIUS_API_KEY"
Real response 200 Captured Oct 28, 2026 · 84 lines (arrays trimmed) 
{
  "data": {
    "account_type": "smart_account",
    "address": "0x3ac82d45ff9e4963cefbc3f74dbe293f34c927ca",
    "delegate": "0x63c0c19a282a1b52b07dd5a65b58948a07dae32b",
    "holdings": [
      {
        "balance": 25,
        "pnl": null,
        "price_confidence": "low",
        "token": {
          "address": "0xfaaf8ffa8a29ceb6c85aff8d3961f65ae1bfc775",
          "logo": null,
          "symbol": "USDG"
        },
        "value_eth": 0.00000500064,
        "value_usd": 0.0117789
      },
      {
        "balance": 25,
        "pnl": null,
        "price_confidence": "low",
        "token": {
          "address": "0x06993ae1230d3755b54f25022028daa66772bc3d",
          "logo": null,
          "symbol": "USDG"
        },
        "value_eth": 0.00000500061,
        "value_usd": 0.0117789
      }
    ],
    "holdings_truncated": false,
    "holdings_value_usd": 0.0235578,
    "is_contract": false,
    "label": null,
    "native_balance": 0.71473787532832551,
    "native_value_usd": 1683.56,
    "pnl": {
      "avg_hold_time_s": null,
      "best_trade": null,
      "gas_scope": "all transactions sent by the wallet in the window",
      "gas_spent_usd": 0.198772,
      "realized_usd": 0,
      "tokens_traded": 0,
      "tokens_with_known_cost": 0,
      "total_usd": 0,
      "trades": 0,
      "unrealized_usd": 0,
      "volume_usd": 0,
      "win_rate_pct": null,
      "window": "30d",
      "worst_trade": null
    },
    "profile": {
      "first_seen_block": 91351250,
      "first_seen_ts": 1792283372000,
      "fresh": false,
      "funded_by": {
        "address": "0xd782268f600403843484b70710daee6846fc0db8",
        "amount_eth": 0.008148386337868892,
        "block": 87601233,
        "label": "bridge:Relay solver",
        "ts": 1791903516300
      },
      "history": "complete",
      "tags": [
        "dev",
        "smart_account"
      ],
      "tx_count": 14,
      "wallet_age_days": 10.8994
    }
  },
  "meta": {
    "balances_block": 100406864,
    "block": 100406864,
    "block_age_ms": 1301,
    "block_ts": 1793225084000,
    "chain": "robinhood",
    "finalized_block": 100397649,
    "lag_ms": 59,
    "safe_block": 100401329
  }
}

What this tells you

  • Both holdings say symbol: "USDG" with balance: 25, but their addresses are 0xfaaf8ffa8a29ceb6c85aff8d3961f65ae1bfc775 and 0x06993ae1230d3755b54f25022028daa66772bc3d, not USDG’s 0x5fc5360d0400a0fd4f2af552add042d716f1d168.
  • Each is valued at value_usd: 0.0117789 with price_confidence: "low": 25 “dollars” worth about one cent. This request has no min_value_usd, so they show up; with min_value_usd=1 they would be hidden.
  • The real value is the ETH: native_balance: 0.71473787532832551, native_value_usd: 1683.56, against holdings_value_usd: 0.0235578.
Wallet profile reference Data looks wrong? Report it

Value balances you already have

Balances change only when the wallet moves tokens; prices change every block. If you already store a wallet’s balances (from an earlier /wallet call or your own indexer), refresh their value with batch prices instead of calling /wallet again. It’s on the anonymous plan and takes up to 100 tokens per call.

Example Anonymous · no key · 1 credit

Prices for the six holdings above, in one call

What are USDG, NVDA, QQQ, ORCL, TTWO and SPY worth right now, so I can revalue the wallet's balances?

GET/v1/robinhood/prices?tokens=0x5fc5360d0400a0fd4f2af552add042d716f1d168,0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec,0xd5f3879160bc7c32ebb4dc785f8a4f505888de68,0xb0992820e760d836549ba69bc7598b4af75dee03,0x5e81213613b6b86eab4c6c50d718d34359459786,0x117cc2133c37b721f49de2a7a74833232b3b4c0c
curl "https://api.crius.sh/v1/robinhood/prices?tokens=0x5fc5360d0400a0fd4f2af552add042d716f1d168,0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec,0xd5f3879160bc7c32ebb4dc785f8a4f505888de68,0xb0992820e760d836549ba69bc7598b4af75dee03,0x5e81213613b6b86eab4c6c50d718d34359459786,0x117cc2133c37b721f49de2a7a74833232b3b4c0c"
Real response 200 Captured Oct 28, 2026 · 74 lines (arrays trimmed) 
{
  "data": {
    "0x117cc2133c37b721f49de2a7a74833232b3b4c0c": {
      "change_24h_pct": 0.732612,
      "confidence": "high",
      "eth": 0.327526,
      "liquidity_usd": 3065474,
      "logo": null,
      "source_pool": "0xfe2a80bb5618fd14984b92ca6d45bf5ba67443ddb1435e28b2e48df2fc1526cd",
      "symbol": "SPY",
      "usd": 772.439
    },
    "0x5e81213613b6b86eab4c6c50d718d34359459786": {
      "change_24h_pct": -2.69804,
      "confidence": "high",
      "eth": 0.0839878,
      "liquidity_usd": 71756.6,
      "logo": null,
      "source_pool": "0xc9dad63b6fb9afe1fe888ebc7b023c587c58b9498f5bd17166226c0995dbc4eb",
      "symbol": "TTWO",
      "usd": 198.077
    },
    "0x5fc5360d0400a0fd4f2af552add042d716f1d168": {
      "change_24h_pct": null,
      "confidence": "high",
      "eth": 0.000424015,
      "liquidity_usd": 10302570,
      "logo": null,
      "source_pool": "0xbac3aa3b91584a53a579b3c999a56756e954e59247e497bad1d25a4334bde551",
      "symbol": "USDG",
      "usd": 1
    },
    "0xb0992820e760d836549ba69bc7598b4af75dee03": {
      "change_24h_pct": 8.82982,
      "confidence": "high",
      "eth": 0.0599593,
      "liquidity_usd": 222938,
      "logo": null,
      "source_pool": "0xc2ce4784e1e72cf0221b51b30c8aaadf6c0b12863cf03ab3687854fb7b1d850a",
      "symbol": "ORCL",
      "usd": 141.408
    },
    "0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec": {
      "change_24h_pct": -1.46967,
      "confidence": "high",
      "eth": 0.0908873,
      "liquidity_usd": 1420235,
      "logo": null,
      "source_pool": "0xd4eb21209c4d6093f80b5b84f5c45cc093ea14a3",
      "symbol": "NVDA",
      "usd": 214.349
    },
    "0xd5f3879160bc7c32ebb4dc785f8a4f505888de68": {
      "change_24h_pct": 0.126576,
      "confidence": "high",
      "eth": 0.305663,
      "liquidity_usd": 1425197,
      "logo": null,
      "source_pool": "0x8493982435e4273028008cd181c84c0d6a548f96792fdb5acddcbb6a8c82d305",
      "symbol": "QQQ",
      "usd": 720.879
    }
  },
  "meta": {
    "block": 100454103,
    "block_age_ms": 745,
    "block_ts": 1793229926000,
    "chain": "robinhood",
    "finalized_block": 100442370,
    "lag_ms": 45,
    "missing": [],
    "safe_block": 100446224
  }
}

What this tells you

  • data is keyed by token address: usd: 214.349 for NVDA, 720.879 for QQQ, 141.408 for ORCL, 198.077 for TTWO, 772.439 for SPY and 1 for USDG, all with confidence: "high".
  • Balance × usd gives the value: 1.117684815247203549 SPY × 772.439 = $863.34, the same as the wallet call’s value_usd: 863.344 (this capture is about two minutes later, at meta.block 100454103).
  • change_24h_pct lets you show a daily move per holding: ORCL is up 8.82982%, TTWO down 2.69804%. USDG’s is null.
  • meta.missing: []: every requested token had a price. Unknown addresses would be listed there instead of in data.
Batch prices reference Runs from your browser on the anonymous plan Data looks wrong? Report it

Balances of one token across wallets

The /wallet call answers “what does this wallet hold”. The opposite question, “who holds this token, and how much”, is the holders endpoint: GET /v1/robinhood/token/{address}/holders ranks up to 500 wallets by balance. In the captured holders sample for Charge AI (0x7b8892cea949bc60d494681d1bc3ea96071ab0b8, request ?limit=5&exclude=infra), the largest real holder 0x1860e8b874ed7742ae5459af731687ecb576c9fd has balance: 28729479.389247917189540117 CHARGE, pct: 2.87295 of supply, worth value_usd: 111.806. Use it when you track one token (an airdrop list, a holder leaderboard) and /wallet when you track one address.

QuestionCallPlan, credits
Every token one wallet holds, with USD valueGET /wallet/{address}?min_value_usd=1Starter, 5
Current prices for balances you already knowGET /prices?tokens=... or POST /pricesAnonymous, 1
Every wallet holding one token, by balanceGET /token/{address}/holders?limit=500Free, 2
One token's holders at a past block or timeGET /token/{address}/holders/snapshot?at=...Free, 5

What the balance fields mean

FieldMeaning
native_balance, native_value_usdETH balance in ETH, and its USD value. Not part of holdings[] or holdings_value_usd.
holdings[].tokenaddress, symbol and logo. Identify tokens by address: symbols are not unique.
holdings[].balanceBalance in whole tokens (the token's decimals already applied), as an exact decimal.
holdings[].value_usd, value_ethBalance × the token's current price, in USD and in ETH.
holdings[].price_confidencehigh, medium, low or none: how far to trust value_usd. See token prices.
holdings_value_usdTotal value_usd of the holdings that pass min_value_usd.
holdings_truncatedtrue when the address touched too many tokens to price them all (pool and router contracts).
meta.balances_blockThe block every balance was read at.

holdings[] is sorted by value_usd, highest first, and holds at most 200 rows. min_value_usd drops every row worth less than the threshold, and that includes tokens with no price at all, so leave it out if you need unpriced tokens too.

Use it in your app

  1. Get a Starter key. /wallet/{address} needs the Starter plan and costs 5 credits per call; send the key in the x-api-key header. See Plans & limits.

  2. Load balances once per wallet. Call /wallet/{address}?min_value_usd=1 when the user opens a portfolio, and store holdings[].token.address and balance.

  3. Refresh value cheaply. Every few seconds, send the stored addresses to /prices (up to 100 per call) and multiply. Call /wallet again only when the wallet sends or receives tokens.

  4. Show trust, not only numbers. Grey out holdings with price_confidence low or none, and never treat a token as USDG or a stock because of its symbol.

// Wallet balances with a total, then a cheap revaluation from batch prices.
const wallet = "0x2a4d34cd09a36f59ae3bedc0880cd5da929321d7";
const headers = { "x-api-key": process.env.CRIUS_API_KEY };


const { data, meta } = await (await fetch(
  `https://api.crius.sh/v1/robinhood/wallet/${wallet}?min_value_usd=1`, { headers })).json();
console.log(`block ${meta.balances_block}: ${data.native_balance} ETH ($${data.native_value_usd})`);
for (const h of data.holdings) {
  console.log(h.token.symbol, h.token.address, h.balance, `$${h.value_usd}`, h.price_confidence);
}
console.log(`total $${data.native_value_usd + data.holdings_value_usd}`);


// Later: revalue the same balances without another /wallet call.
const tokens = data.holdings.map((h) => h.token.address).join(",");
const prices = (await (await fetch(`https://api.crius.sh/v1/robinhood/prices?tokens=${tokens}`)).json()).data;
const now = data.holdings.reduce((sum, h) => sum + Number(h.balance) * (prices[h.token.address]?.usd ?? 0), 0);
console.log(`token holdings now $${now.toFixed(2)}`);

Frequently asked questions

Is there a Robinhood Chain balances API?

Yes. GET https://api.crius.sh/v1/robinhood/wallet/{address} returns a wallet's ETH balance and every token it holds with a balance and USD value, in one call, without you having to know which tokens to ask for. It needs a Starter key (5 credits per call). Crius finds the tokens from the wallet's transfer history and reads the balances on-chain at one block.

How do I get all token balances of a wallet on Robinhood Chain?

Call /wallet/{address}?min_value_usd=1. holdings[] lists up to 200 tokens with a balance, most valuable first: token.address, token.symbol, balance (decimals already applied), value_usd and price_confidence. The ETH balance is separate, in native_balance. holdings_value_usd is the total of the token holdings.

Are the balances read from the chain?

Yes. The most valuable holdings are checked against each token's own balanceOf, and the ETH balance is read with eth_getBalance, both at the block in meta.balances_block. Tokens whose balanceOf returns 0 are left out, even if their Transfer events say otherwise.

How do I get the balance of one token for many wallets?

Turn the question around: GET /v1/robinhood/token/{address}/holders?limit=500 lists the token's holders ranked by balance, with balance, pct of supply and value_usd for each (Free plan, 2 credits). For a past block or time, use the holder snapshot.

Does the balances call include tokenized stocks and USDG?

Yes. Tokenized stocks (NVDA, QQQ, SPY and others) and USDG are ERC-20 tokens on Robinhood Chain, so they appear in holdings[] like any other token, valued from their on-chain pools. Real USDG is 0x5fc5360d0400a0fd4f2af552add042d716f1d168: match by address, because anyone can deploy a token called USDG.

Guide Wallet holdings & PnL Get a Robinhood Chain wallet's tokens with USD value, ETH balance, realized and unrealized PnL, win rate, gas spent and wallet tags in one call. Real example. Read Guide Prices for many tokens Price up to 100 Robinhood Chain tokens in one request with the batch prices API, or get chosen profile fields for many tokens. Real responses, no key needed. Read Guide Token holders Robinhood Chain token holders API: get any token's top holders in one call, with balance, share of supply, USD value, labels, holder count and top-10 share. Read Use case Wallets & portfolios What a Robinhood Chain wallet or portfolio app needs from the Crius API: holdings, USD values, PnL, trade history and warnings about spam tokens. Read Concept Token prices How the Crius API prices Robinhood Chain tokens from on-chain pools, how the price pool is picked, and what confidence and thin_liquidity mean. Read API reference Wallet profile API Holdings with USD value, realized and unrealized PnL over a window (1d, 7d, 30d, all), win rate and wallet tags. Read

Get your free Crius API key

Every example on this page works with a free key: higher rate limits than the anonymous plan, holders, wallets and the WebSocket stream. No card needed.

Get a free API key See plans
  • Robinhood Chain (4663) only, from our own archive nodes
  • REST + WebSocket
  • Pay on-chain or by card