Sandbox version
For experimental use only. Proceed with caution.
richlist
Token richlist distribution: %-of-supply buckets + top-N percentile thresholds
get
/richlist/token/{tokenSlug}/info
operationId: richlist-tokenInfo

Per-token mirror of /richlist/native/info. Returns totalHolders + totalSupply + totalHeld for the dataset, plus two parallel views over every non-issuer trustline with a non-zero balance: (1) byRange — account count + sum of token balance per %-of-supply bucket ([0, 0.001%), [0.001%, 0.01%), …, [25%, ∞)). Bucket edges are %-of-supply rather than absolute amounts because token supplies vary by orders of magnitude across the index, so absolute thresholds (like XRP's 20 / 500 / 1k / …) would be meaningless cross-token. (2) byPercentile — for each percentile in [0.01%, 0.1%, 0.2%, 0.5%, 1%, 2%, 3%, 4%, 5%, 10%], the number of holders in the top-N slice and the minimum balance required to be in it. The issuer account is excluded from both views — its negative balance mirrors outstanding supply rather than a holder position. Falls back to a live computation when no snapshot has been recorded for this token yet (new token / first snapshot pending).

Unlock protected endpoints

Enter your Bearer token once to enable every protected route in this API reference.

HTTP bearer

Saved for this browser tab only. The credential is never sent until you test an endpoint.

Authorizations
NameLocationDetails
BearerAuthAuthorization header · bearerJWT issued by the Honeycluster auth service for the `indexer` audience. Present as `Authorization: Bearer <token>`.
Path Parameters
NameTypeDefaultDescription
tokenSlug
required
string
Natural token identifier in `currency.issuer` form. Example: `USD.rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B`.
Responses
200
application/json
Successful response
FieldTypeDescription
totalHolders
integer
Number of non-issuer trustlines with a non-zero balance for this token.
totalSupply
object
Token total supply used as the denominator for the `byRange` bucket boundaries. `null` when supply has not been recorded yet — in which case `byRange` entries all evaluate to count=0 and the percentile half is still meaningful.
totalHeld
string
Sum of non-issuer holder balances, as a decimal string. Equals or is less than `totalSupply` (issuer-held + locked tokens are excluded).
byRange
object[]
Holder-count + balance-sum partitioned across %-of-supply buckets ([0, 0.001%), [0.001%, 0.01%), …, [25%, ∞)). `min` / `max` are percentages of `totalSupply` (e.g. `0.01` = 0.01% of supply). Order matches `TOKEN_RICHLIST_RANGES_PCT`. Empty buckets surface as `accountCount=0, sumBalance="0"`.
byRange[].min
number
Inclusive lower bound for this bucket. XRP-side: balance in XRP. Token-side: balance as a percentage of total supply (e.g. `0.01` = 0.01%).
byRange[].max
object
Exclusive upper bound, or `null` for the open-ended top bucket. Same unit as `min`.
byRange[].accountCount
integer
Number of accounts whose balance falls inside the half-open `[min, max)` range.
byRange[].sumBalance
string
Sum of balances of accounts in this bucket, as a decimal string. XRP-side: in XRP. Token-side: in token base units.
byPercentile
object[]
Top-N percentile thresholds — for each entry, how many holders are in the top-N slice and the minimum token balance to be in it. Order matches `XRP_RICHLIST_PERCENTILES` (the same 0.01% → 100% ladder is reused; the unit is unit-invariant).
byPercentile[].percentile
number
Top-N percentile as a decimal (e.g. `0.01` for "top 1%", `0.0001` for "top 0.01%", `1.0` for the entire population).
byPercentile[].accountCount
integer
Number of accounts in the top-N percentile (= ceil(percentile × totalHolders)).
byPercentile[].balanceAtOrAbove
object
Balance threshold such that every account in the top-N percentile holds at least this amount, as a decimal string. `null` when the dataset is empty.
Example
Json
{
  "totalHolders": 0,
  "totalSupply": "string",
  "totalHeld": "string",
  "byRange": [
    {
      "min": 0,
      "max": 0,
      "accountCount": 0,
      "sumBalance": "string"
    }
  ],
  "byPercentile": [
    {
      "percentile": 0,
      "accountCount": 0,
      "balanceAtOrAbove": "string"
    }
  ]
}
400
application/json
Invalid input data
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}
401
application/json
Authorization not provided
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}
403
application/json
Insufficient access
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}
404
application/json
Not found
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "NOT_FOUND",
  "message": "Not found",
  "issues": []
}
500
application/json
Internal server error
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}