Skip to main content
GET
Get Token Holders
Credit cost: 1 per request.
Get the top holders of any given token.
All tokens are supported by default, including NFT collections, but beware of errors: a 404 will be returned if no holders are found, and a 400 might be returned for some rare unsupported tokens.
You’ll find the parameters and response schemas at the end of this page, but here’s some additional context:

Parameters

  • The base response includes the top 80 holders of the token. This is the same as the iFrame integrations. You can change the number of holders with the limit parameter.
  • The return_metadata query parameter includes the labels and metadata of the holders in the response.
  • Data can be cached for performance, cache TTL depends on token age. Date of update can be found in the X-Dt-Update response header. If you need to force a refresh, you can use the refresh=true query param.
  • History mode: to access the top holders of a token in a specific date in the past, use the timestamp parameter (unix timestamp)

Response

  • All share values are in [0, 1] format, meaning 42% will be returned as 0.42.
  • When return_metadata=true, the is_paid_label boolean indicates whether the label is a community-submitted label.

Authorizations

X-ApiKey
string
header
required

Path Parameters

chain
enum<string>
required
Available options:
eth,
base,
solana,
tron,
bsc,
sonic,
ton,
avalanche,
polygon,
monad,
hyperevm,
arbitrum,
robinhood
token_address
string
required

Query Parameters

limit
enum<integer>
default:80
Available options:
80,
250,
500
timestamp
integer | null
refresh
boolean
default:false
return_metadata
boolean
default:false

Response

Successful Response

address
string
required
holder_data
HolderData · object
required
address_details
AccountAddressDetails · object | null