List ranked holders of a token
Holders ranked by balance descending, then holder ascending. For a classic asset this is one merged list of trustline and SAC contract holders. Zero balances only with include=zero. Deep pages are cursor-only. With as_of_ledger the holders are read at a past ledger from the balance history (credit class assets-history, weight 5); holder_count is the count at that ledger, and the supply key is present and null (supply_source does not apply); assets with more than 100,000 holders answer 409 and need a snapshot job. Credit class assets-holders: 5 × ceil(rows/100), at least one credit per started 64 KiB. Publishable keys are not allowed.
- Unknown or repeated query parameters return 400, so a typo or an unsupported filter never returns unfiltered data.
Authorizations
Send Authorization: Bearer <key>, the same keys as Activity and RPC. Testnet: lum_test_…; Mainnet: lum_live_…. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable lum_pub_… keys work only on the routes marked "Publishable keys allowed", from an allowed browser origin.
Path Parameters
native, CODE:ISSUER (case-sensitive, never padded), a C… token contract ID or pool:<64 hex>. A Stellar Asset Contract ID is accepted as an alias and resolves to its classic CODE:ISSUER.
"BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX"
Query Parameters
Decimal; holders below it are left out.
^[0-9]+(\.[0-9]+)?$"1"
zero: also list zero balances (trustlines that hold nothing).
zero Read at this past ledger from the balance history (credit class assets-history, weight 5). 400 when after the latest applied ledger; 409 when the history cannot answer it exactly. Not available to publishable keys.
x >= 15300000
Records per page, 1 to 200 (default 50).
1 <= x <= 20010
Resume after this paging_token. Prefer following _links.next.href.
Response
A page of holders with the asset's holder count and supply.
Effective page size: default 50, maximum 200.
Canonical asset ID: native, CODE:ISSUER (case-sensitive, never padded), a C… contract ID for a custom token, or pool:<64 hex> for a liquidity pool share. A Stellar Asset Contract ID is accepted as an alias and resolves to its classic CODE:ISSUER.
Holders with a non-zero balance; with as_of_ledger, the count at that ledger.
x >= 0Asset supply as on the registry record (trustlines and contract balances including archived; no claimable balances or pool reserves). Null while not computed, and always null with as_of_ledger (the key stays present). Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float.
exact, derived Decimals used for balance and supply; null when a custom token's decimals are unknown.
0 <= x <= 38Present when the request named the asset by another ID.