Skip to main content
GET
/
v0
/
tokens
/
holders
/
{chain}
/
{token_address}
Get Token Holders
curl --request GET \
  --url https://api.bubblemaps.io/v0/tokens/holders/{chain}/{token_address} \
  --header 'X-ApiKey: <api-key>'
[
  {
    "address": "<string>",
    "holder_data": {
      "amount": 123,
      "rank": 123,
      "share": 123
    },
    "address_details": {
      "degree": 123,
      "is_supernode": true,
      "is_contract": true,
      "is_cex": true,
      "is_dex": true,
      "inward_relations": 123,
      "outward_relations": 123,
      "label": "<string>",
      "entity_id": "<string>",
      "first_activity_date": "2023-11-07T05:31:56Z"
    }
  }
]
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)
OptionCredits
Base request1
limit=250+10
limit=500+25
return_metadata=true+25
refresh=true+25
timestamp=XXX+50

​
Response

  • All share values are in [0, 1] format, meaning 42% will be returned as 0.42.

Authorizations

​
X-ApiKey
string
header
required

Path Parameters

​
chain
enum<string>
required
Available options:
eth,
base,
solana,
tron,
bsc,
apechain,
sonic,
ton,
avalanche,
polygon,
monad,
hyperevm,
arbitrum
​
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