Requires the Stock Token API add-on on a Robinhood Chain mainnet endpoint (chain ID 4663). Testnet is not supported. See the Stock Token API overview for setup and conventions.

Parameters

address

string

REQUIRED

Wallet or contract address to query.

options

object

Optional filters and read options. Unknown keys are rejected with -32602.

includeUsd

boolean

Include USD prices and valuations. Defaults to true. False makes valuation fields null.

includeZero

boolean

Include zero balances. Defaults to false.

symbols

array

Case-insensitive stock tickers. Unknown tickers are skipped. Omit to use all tokens or registered feeds.

blockTag

string

Block to read: a hex block number, block hash, latest (default), safe, or finalized. All on-chain reads use this one block.

Returns

result

object

The stock token API result at the reported block.

blockNumber

string

Snapshot block number in hexadecimal. Nested event block numbers are integers.

blockHash

string

Hash of the snapshot block.

holdings

array

One entry per token held (every token with includeZero), sorted by symbol. A wallet holding nothing returns []. Delisted (INACTIVE) tokens are not included.

token

string

Stock token contract address.

symbol

string

Stock ticker or priced asset symbol.

balanceRaw

string

What balanceOf returns: raw units, 18 decimals, before the multiplier.

uiMultiplier

string

The token's multiplier at this block (10^18 scale, and as a decimal string).

uiMultiplierDecimal

string

The token's multiplier at this block (10^18 scale, and as a decimal string).

balanceUi

string

Shares held, 18 decimals: floor(raw × multiplier / 10^18). Equals the token's balanceOfUI, exactly.

balanceUiDecimal

string

Shares as a decimal string, e.g. 1.478304943464125782. Show this to users.

pending

object or null

Scheduled multiplier change, or null when no change is pending.

uiMultiplier

string

Scheduled multiplier scaled by 10^18.

uiMultiplierDecimal

string

Scheduled multiplier as a decimal string.

effectiveAt

integer

Unix seconds when the change takes effect.

effectiveAtIso

string

The effective time in ISO 8601 format.

priceUsd

string or null

The Chainlink price in USD (8 decimals), already including the multiplier. null if the token has no feed. May be null when unavailable or not applicable.

priceUpdatedAt

integer or null

When the feed last updated (Unix seconds). May be null when unavailable or not applicable.

priceStale

boolean or null

true if the feed was older than its threshold (1.5 × its heartbeat, 24 h for Robinhood feeds) at the block's time, while it was expected to update. The same rule as qn_getOracleHealth. Show stale prices with a caution. A paused feed still values the holding with its held price; check oraclePaused in qn_getStockTokens. May be null when unavailable or not applicable.

valueUsd

string or null

The holding's value in USD. May be null when unavailable or not applicable.

balanceUiAfterPending

string

Present only when pending is set: shares after the change, scaled by 10^18.

balanceUiAfterPendingDecimal

string

Present only when pending is set: shares after the change as a decimal string.

totalValueUsd

string or null

The sum of valueUsd over the holdings that have a price. null with includeUsd: false (as is totalValueUsdComplete). May be null when unavailable or not applicable.

totalValueUsdComplete

boolean or null

true only if every holding has a price. False when a holding has no price. May be null when unavailable or not applicable.

warnings

array

Warning code strings describing partial data or unavailable signals; empty when there are no warnings.

Request

1
curl -X POST "https://docs-demo.robinhood-mainnet.quiknode.pro/" \
2
  -H "Content-Type: application/json" \
3
  -d '{
4
  "jsonrpc": "2.0",
5
  "method": "qn_getStockTokenBalances",
6
  "params": [
7
    "0x5a3482713051b71f1daeb532567121546ff650f9",
8
    {
9
      "symbols": [
10
        "AMC",
11
        "NVDA"
12
      ]
13
    }
14
  ],
15
  "id": 1
16
}'

1
curl -X POST "https://docs-demo.robinhood-mainnet.quiknode.pro/" \
2
  -H "Content-Type: application/json" \
3
  -d '{
4
  "jsonrpc": "2.0",
5
  "method": "qn_getStockTokenBalances",
6
  "params": [
7
    "0x5a3482713051b71f1daeb532567121546ff650f9",
8
    {
9
      "symbols": [
10
        "AMC",
11
        "NVDA"
12
      ]
13
    }
14
  ],
15
  "id": 1
16
}'

1
const body = {
2
    jsonrpc: '2.0',
3
    method: 'qn_getStockTokenBalances',
4
    params: ["0x5a3482713051b71f1daeb532567121546ff650f9",{"symbols":["AMC","NVDA"]}],
5
    id: 1
6
}
7

8
async function main() {
9
    const response = await fetch('https://docs-demo.robinhood-mainnet.quiknode.pro/', {
10
        method: 'POST',
11
        headers: {'Content-Type': 'application/json'},
12
        body: JSON.stringify(body)
13
    })
14
    const data = await response.json()
15
    console.log(data)
16
}
17

18
main()

1
const body = {
2
    jsonrpc: '2.0',
3
    method: 'qn_getStockTokenBalances',
4
    params: ["0x5a3482713051b71f1daeb532567121546ff650f9",{"symbols":["AMC","NVDA"]}],
5
    id: 1
6
}
7

8
async function main() {
9
    const response = await fetch('https://docs-demo.robinhood-mainnet.quiknode.pro/', {
10
        method: 'POST',
11
        headers: {'Content-Type': 'application/json'},
12
        body: JSON.stringify(body)
13
    })
14
    const data = await response.json()
15
    console.log(data)
16
}
17

18
main()

1
import requests
2
import json
3

4
url = "https://docs-demo.robinhood-mainnet.quiknode.pro/"
5

6
payload = json.dumps({
7
  "jsonrpc": "2.0",
8
  "method": "qn_getStockTokenBalances",
9
  "params": [
10
    "0x5a3482713051b71f1daeb532567121546ff650f9",
11
    {
12
      "symbols": [
13
        "AMC",
14
        "NVDA"
15
      ]
16
    }
17
  ],
18
  "id": 1
19
})
20
headers = {
21
  'Content-Type': 'application/json'
22
}
23

24
response = requests.request("POST", url, headers=headers, data=payload)
25

26
print(response.text)

1
import requests
2
import json
3

4
url = "https://docs-demo.robinhood-mainnet.quiknode.pro/"
5

6
payload = json.dumps({
7
  "jsonrpc": "2.0",
8
  "method": "qn_getStockTokenBalances",
9
  "params": [
10
    "0x5a3482713051b71f1daeb532567121546ff650f9",
11
    {
12
      "symbols": [
13
        "AMC",
14
        "NVDA"
15
      ]
16
    }
17
  ],
18
  "id": 1
19
})
20
headers = {
21
  'Content-Type': 'application/json'
22
}
23

24
response = requests.request("POST", url, headers=headers, data=payload)
25

26
print(response.text)

1
require "uri"
2
require "json"
3
require "net/http"
4

5
uri = URI("https://docs-demo.robinhood-mainnet.quiknode.pro/")
6

7
payload = {
8
  jsonrpc: "2.0",
9
  id: 1,
10
  method: "qn_getStockTokenBalances",
11
  params: ["0x5a3482713051b71f1daeb532567121546ff650f9",{"symbols":["AMC","NVDA"]}]
12
}
13

14
request = Net::HTTP::Post.new(uri)
15
request["Content-Type"] = "application/json"
16
request.body = JSON.generate(payload)
17

18
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
19
  http.request(request)
20
end
21

22
puts response.body

1
require "uri"
2
require "json"
3
require "net/http"
4

5
uri = URI("https://docs-demo.robinhood-mainnet.quiknode.pro/")
6

7
payload = {
8
  jsonrpc: "2.0",
9
  id: 1,
10
  method: "qn_getStockTokenBalances",
11
  params: ["0x5a3482713051b71f1daeb532567121546ff650f9",{"symbols":["AMC","NVDA"]}]
12
}
13

14
request = Net::HTTP::Post.new(uri)
15
request["Content-Type"] = "application/json"
16
request.body = JSON.generate(payload)
17

18
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
19
  http.request(request)
20
end
21

22
puts response.body

Response

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": {
5
    "blockNumber": "0x5b9ec07",
6
    "blockHash": "0x952998db38778ebb03eaee447eed56f9e22989a5290b0cb9532d98d397d01aeb",
7
    "holdings": [
8
      {
9
        "token": "0x05a3d1Cd21d0C88145E82600E62e7E496e0F222B",
10
        "symbol": "AMC",
11
        "balanceRaw": "2785793951229957535",
12
        "uiMultiplier": "1000000000000000000",
13
        "uiMultiplierDecimal": "1.0",
14
        "balanceUi": "2785793951229957535",
15
        "balanceUiDecimal": "2.785793951229957535",
16
        "pending": null,
17
        "priceUsd": null,
18
        "priceUpdatedAt": null,
19
        "priceStale": null,
20
        "valueUsd": null
21
      },
22
      {
23
        "token": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
24
        "symbol": "NVDA",
25
        "balanceRaw": "1479717615357604551",
26
        "uiMultiplier": "1000775159164630595",
27
        "uiMultiplierDecimal": "1.000775159164630595",
28
        "balanceUi": "1480864632028214327",
29
        "balanceUiDecimal": "1.480864632028214327",
30
        "pending": null,
31
        "priceUsd": "212.23688993",
32
        "priceUpdatedAt": 1792769036,
33
        "priceStale": false,
34
        "valueUsd": "314.05066465"
35
      }
36
    ],
37
    "totalValueUsd": "314.05066465",
38
    "totalValueUsdComplete": false,
39
    "warnings": [
40
      "PRICE_UNAVAILABLE:AMC"
41
    ]
42
  }
43
}

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": {
5
    "blockNumber": "0x5b9ec07",
6
    "blockHash": "0x952998db38778ebb03eaee447eed56f9e22989a5290b0cb9532d98d397d01aeb",
7
    "holdings": [
8
      {
9
        "token": "0x05a3d1Cd21d0C88145E82600E62e7E496e0F222B",
10
        "symbol": "AMC",
11
        "balanceRaw": "2785793951229957535",
12
        "uiMultiplier": "1000000000000000000",
13
        "uiMultiplierDecimal": "1.0",
14
        "balanceUi": "2785793951229957535",
15
        "balanceUiDecimal": "2.785793951229957535",
16
        "pending": null,
17
        "priceUsd": null,
18
        "priceUpdatedAt": null,
19
        "priceStale": null,
20
        "valueUsd": null
21
      },
22
      {
23
        "token": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
24
        "symbol": "NVDA",
25
        "balanceRaw": "1479717615357604551",
26
        "uiMultiplier": "1000775159164630595",
27
        "uiMultiplierDecimal": "1.000775159164630595",
28
        "balanceUi": "1480864632028214327",
29
        "balanceUiDecimal": "1.480864632028214327",
30
        "pending": null,
31
        "priceUsd": "212.23688993",
32
        "priceUpdatedAt": 1792769036,
33
        "priceStale": false,
34
        "valueUsd": "314.05066465"
35
      }
36
    ],
37
    "totalValueUsd": "314.05066465",
38
    "totalValueUsdComplete": false,
39
    "warnings": [
40
      "PRICE_UNAVAILABLE:AMC"
41
    ]
42
  }
43
}

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free

Response details

Field	Description
blockNumber, blockHash	The block every balance and price was read at: one consistent snapshot.
holdings[]	One entry per token held (every token with includeZero), sorted by symbol. A wallet holding nothing returns []. Delisted (INACTIVE) tokens are not included.
totalValueUsd	The sum of valueUsd over the holdings that have a price. null with includeUsd: false (as is totalValueUsdComplete).
totalValueUsdComplete	true only if every holding has a price. A holding without a usable price makes this false.
warnings	See Warnings.

Each holding:

Field	Description
token, symbol	The token.
balanceRaw	What balanceOf returns: raw units, 18 decimals, before the multiplier.
uiMultiplier, uiMultiplierDecimal	The token's multiplier at this block (10^18 scale, and as a decimal string).
balanceUi	Shares held, 18 decimals: floor(raw × multiplier / 10^18). Equals the token's balanceOfUI, exactly.
balanceUiDecimal	Shares as a decimal string, e.g. 1.478304943464125782. Show this to users.
pending	A scheduled multiplier change, or null (same shape as in qn_getStockTokens).
balanceUiAfterPending, balanceUiAfterPendingDecimal	Present only when pending is set: the share count once the change takes effect.
priceUsd	The Chainlink price in USD (8 decimals), already including the multiplier. null if the token has no feed.
priceUpdatedAt	When the feed last updated (Unix seconds).
priceStale	true if the feed was older than its threshold (1.5 × its heartbeat, 24 h for Robinhood feeds) at the block's time, while it was expected to update. The same rule as qn_getOracleHealth. Show stale prices with a caution. A paused feed still values the holding with its held price; check oraclePaused in qn_getStockTokens.
valueUsd	The holding's value in USD.

How valueUsd is computed

Robinhood's feeds quote the price per raw token: they already fold in the multiplier. So:

The USD value is (balanceRaw / 10^18) × priceUsd, rounded down to eight decimal places. Use balanceRaw here; using balanceUi would apply the multiplier twice.

The value is computed in integers and rounded down to the feed's 8 decimals, so it never drifts through floating point.

Warnings

Warning	Meaning
PRICE_UNAVAILABLE:<SYMBOL>	The token has no usable price: no feed at this block, the read failed, or the answer is invalid (zero, negative or never set). Its balance is still returned.
READ_FAILED:<SYMBOL>	Reading the balance failed at this block; the token is left out.
MULTIPLIER_NOT_APPLIED:<SYMBOL>	A scheduled change is past its effectiveAt, but the contract still reports the old multiplier. The contract's value is used.

Errors

Code	When
-32602	address is missing or malformed (data.field: "address"), an unknown option, or an unknown blockTag.
-32002	blockTag is ahead of the chain head.

Performance

Balances are read in two batched passes at the chosen block: every token's balance, then multipliers and prices for the tokens held. At latest that typically takes under 100 ms (measured at the service). At older blocks it's slower, because the node reads each token's state as of that block: typically under a second, even a month back.