GET /holders/list/{id}
GET

/v1/holders/list/{id}

Paginated holder richlist with acquisition tracking

AuthNone — works without a key

Request

GEThttps://api.xrpl.to/v1/holders/list/0dd550278b74cb6690fdae351e8e0df3
Path parameterValueDescription
idA token id: its md5, slug or issuer_currency
Query parameterValueDescription
offsetint
limitint (default: 20, max 200)
freezebool - only frozen trustlines (for an MPT: only holders the issuer locked)
sortbalance|value|holding|percent|change24h|pnl (value/percent are balance/holding aliases; default: balance desc)
orderasc|desc
searchaccount address (min 3 chars)
minBalancefloat - min balance (token units)
maxBalancefloat - max balance (token units)
curl 'https://api.xrpl.to/v1/holders/list/0dd550278b74cb6690fdae351e8e0df3'

Response

200Example response61 ms · just now · 2.8 KB · 120 lines
https://api.xrpl.to/v1/holders/list/0dd550278b74cb6690fdae351e8e0df3
{
  "success": true,
  "took": 55,
  "summary": {
    "top10Hold": 81.5,
    "top20Hold": 91.1,
    "top50Hold": 97.6,
    "top100Hold": 98.2,
    "gini": 0.9997,
    "hhi": 1072,
    "frozen": 1,
    "lockedPct": 0
  },
  "length": 68205,
  "richList": [
    {
      "account": "rfKSkASYSGwrTvk9FeH65QC5CWiiEjYFpp",
      "balance": 143000008,
      "freeze": false,
      "id": 1,
      "holding": 18.6,
      "isCreator": false,
      "rank": 1,
      "xrpBalance": 49.49561,
      "lastActive": 1793776632,
      "name": null,
      "domain": null,
      "funder": {
        "account": "raQxZLtqurEXvH5sgijrif7yXMNwvFRkJN",
        "name": "Bybit",
        "fundedCount": 4,
        "fundedAt": 1741947450000,
        "amountXrp": 50
      }
    },
    {
      "account": "rEq4b7nbL2ep44Fgk9bPwpynGRjyESpf5B",
      "balance": 141650041.6700765,
      "freeze": false,
      "balance24h": 144150041.6700765,
      "id": 2,
      "holding": 18.43,
      "isCreator": false,
      "rank": 2,
      "xrpBalance": 174411002.397372,
      "lastActive": 1795197782,
      "name": "Gemini",
      "domain": null,
      "funder": {
        "account": "raBQUYdAhnnojJQ6Xi3eXztZ74ot24RDq1",
        "name": "Gemini",
        "fundedCount": 11469,
        "fundedAt": 1761243532000,
        "amountXrp": 2.42
      }
    },
    {
      "account": "rKWoRYn65imVUUF2Hmtpp78E6NAjTf6ExL",
      "balance": 105000000.0000102,
      "freeze": false,
      "id": 3,
      "holding": 13.66,
      "isCreator": false,
      "rank": 3,
      "xrpBalance": 90.602637,
      "lastActive": 1791908100,
      "name": null,
      "domain": null,
      "funder": {
        "account": "rsM7KAW1wutm2qxeF2FUWb9yRmSPjjS2Ex",
        "name": null,
        "fundedCount": 2,
        "fundedAt": 1783600322000,
        "amountXrp": 10
      }
    },
    {
      "account": "rPz2qA93PeRCyHyFCqyNggnyycJR1N4iNf",
      "balance": 71740275.576,
      "freeze": false,
      "balance24h": 31608112.884,
      "id": 4,
      "holding": 9.33,
      "isCreator": false,
      "rank": 4,
      "xrpBalance": 594973768.86576,
      "lastActive": 1795191471,
      "name": "Binance",
      "domain": null,
      "funder": {
        "account": "rPJ5GFpyDLv7gqeB1uZVUBwDwi41kaXN5A",
        "name": "Binance",
        "fundedCount": 1,
        "fundedAt": 1703171120000,
        "amountXrp": 70
      }
    },
    {
      "account": "r39TAwuqkA5BNxxfL5YXewRGtCgBcADjcx",
      "balance": 56550138.6340507,
      "freeze": false,
      "balance24h": 54015334.6840507,
      "id": 5,
      "holding": 7.35,
      "isCreator": false,
      "rank": 5,
      "xrpBalance": 5868672.56623,
      "lastActive": 1795219992,
      "name": null,
      "domain": null,
      "funder": {
        "account": "rNGkoJhnzWTs9RtEnCSziqNLpxfx3ysf8J",
        "name": null,
        "fundedCount": 4,
        "fundedAt": 1743532350000,
        "amountXrp": 20
      }
    }
  ]
}

Long arrays and strings are shortened in the example; Send request for the full answer.

Shapeas documented
{
  success,
  took,
  summary: {
    top10Hold,
    top20Hold,
    top50Hold,
    top100Hold,
    frozen,
    lockedPct (share of total issued supply in escrow)
  },
  length (total holders; filtered count when search/minBalance/maxBalance set),
  richList[]: {
    account,
    balance,
    holding,
    rank,
    freeze,
    frozenByIssuer?,
    isCreator,
    xrpBalance,
    lastActive,
    name,
    domain,
    funder,
    tradedPct?,
    tradeCount?,
    source?,
    acquisition?,
    isAMM?,
    isInsider? / deadPool? / burned? (the row is left out of circulating supply: insiderPct,
    deadPoolPct and burnedPct on the token),
    pnl? (realized+residual XRP),
    roi?,
    unrealized?,
    bought?/sold? (XRP volume),
    lastTrade?
  }
}

What it does

Paginated holder richlist with acquisition tracking

A token id can be its md5, slug or issuer_currency. How to build an md5 →
OpenAPI