richlist
XRP richlist concentration evolution over time
get
/richlist/native/timeseries
operationId: richlist-nativeTimeseries

Returns a paginated daily time series of the XRP richlist concentration shape — same byRange (canonical XRP balance buckets) + byPercentile (top-N thresholds) + totals as /richlist/native/info, but one row per day. Pages are ordered oldest → newest internally; cursor walks BACK in time — nextCursor is the previous page's oldest day, and the next call (with cursor=…) returns rows older than that. limit is the page size (default 30, max 365). Days with no snapshot are absent from the array (gaps are visible rather than smoothed); cursor pagination still works normally across gaps.

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>`.
Query Parameters
NameTypeDefaultDescription
cursor
string
limit
integer30
Responses
200
application/json
Successful response
FieldTypeDescription
items
object[]
One point per day, ordered oldest → newest within the page. Empty when the snapshot worker has not yet populated the requested window.
items[].bucketDay
string
UTC day bucket the row aggregates, ISO-8601 date (`YYYY-MM-DD`). Always at midnight UTC.
items[].totalHolders
integer
Funded-account count for that day.
items[].totalSupply
object
Total XRP supply observed at snapshot time, decimal string. Mirrors the token-side field so the timeseries point shape matches across XRP and token endpoints.
items[].totalHeld
string
Sum of XRP balances across funded accounts for that day, decimal string.
items[].byRange
object[]
Same canonical XRP balance buckets as `/richlist/native/info`, materialized per day.
items[].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%).
items[].byRange[].max
object
Exclusive upper bound, or `null` for the open-ended top bucket. Same unit as `min`.
items[].byRange[].accountCount
integer
Number of accounts whose balance falls inside the half-open `[min, max)` range.
items[].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.
items[].byPercentile
object[]
Same top-N percentile thresholds as `/richlist/native/info`, materialized per day.
items[].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).
items[].byPercentile[].accountCount
integer
Number of accounts in the top-N percentile (= ceil(percentile × totalHolders)).
items[].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.
nextCursor
object
Opaque cursor for the next-older page, or `null` when this page is the oldest available. Pass it back as `cursor` to walk further back in time.
Example
Json
{
  "items": [
    {
      "bucketDay": "string",
      "totalHolders": 0,
      "totalSupply": "string",
      "totalHeld": "string",
      "byRange": [
        {
          "min": 0,
          "max": 0,
          "accountCount": 0,
          "sumBalance": "string"
        }
      ],
      "byPercentile": [
        {
          "percentile": 0,
          "accountCount": 0,
          "balanceAtOrAbove": "string"
        }
      ]
    }
  ],
  "nextCursor": "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": []
}