---
title: "The largest holders"
method: GET
path: "/rich_list/{network}"
tags: ["Network & price"]
---

# The largest holders

`GET /rich_list/{network}`

## Request

- Base URL: `https://sochain.com/api/v3`
- URL: `https://sochain.com/api/v3/rich_list/{network}`
- Auth: one of:
  - none
  - API key in header `API-KEY`
  - API key in query parameter `api_key`

The top 1,000 addresses by confirmed balance, a page at a time, with each one's share of all coins, transactions, first and last activity, and 24-hour and 7-day change. Follows the newest block.

## Path parameters

- `network` 'BTC' | 'LTC' | 'DOGE' | 'ZEC' | 'BTCTEST' | 'LTCTEST' | 'DOGETEST' | 'ZECTEST', required

## Query parameters

- `page` integer
- `page_size` 25 | 50 | 100

## Response `200`

Success.

- object
  - `status` 'success', required
  - `data` RichList, required
    - `height` integer, required: The newest block the list reflects.
    - `time` integer, required
    - `supply` string, required: An exact decimal amount of coins with 8 decimals. Signed amounts may start with '-'. Parse as an integer of the smallest unit, not a float.
    - `page` integer, required
    - `page_size` integer, required
    - `total_rows` integer, required: Holders listed, at most 1,000.
    - `rows` object[], required
      - `rank` integer
      - `address` string, nullable: null for coins in outputs with no address (pay-to-public-key, bare multisig).
      - `balance` string: An exact decimal amount of coins with 8 decimals. Signed amounts may start with '-'. Parse as an integer of the smallest unit, not a float.
      - `received` string: An exact decimal amount of coins with 8 decimals. Signed amounts may start with '-'. Parse as an integer of the smallest unit, not a float.
      - `sent` string: An exact decimal amount of coins with 8 decimals. Signed amounts may start with '-'. Parse as an integer of the smallest unit, not a float.
      - `share_of_supply` number, nullable
      - `tx_count` integer
      - `first_seen` object, nullable: {height, time} of that activity.
        - `height` integer
        - `time` integer
      - `last_seen` object, nullable: {height, time} of that activity.
        - `height` integer
        - `time` integer
      - `delta_24h` string, nullable: Balance change over 24 hours, 8 decimals.
      - `delta_7d` string, nullable: Over 7 days.
      - `label` unknown

## Other responses

- `400`: A bad parameter or body; the message says which.
- `401`: An invalid key, no key where one is needed (buckets, webhooks, /account_info), a locked account or expired plan, or both the month's requests and the keyless rate used up. Kept as 401, with this message, for v3 compatibility.
- `404`: Unknown network, or a network without a rich list.
- `429`: Without a key, past the day's 2,500 lookups from this IP while SoChain is busy (Retry-After: 60), or past the day's most (Retry-After: seconds to 00:00 UTC). With or without one, too many requests in flight at once (Retry-After: 1, not counted).
- `503`: Briefly unavailable; retry with backoff. May carry Retry-After.

---

[API](https://skmtc.dev/sochain/apis/sochain-api.md) · [All operations](https://skmtc.dev/sochain/apis/sochain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sochain/apis/sochain-api/revisions/80682797b38f?raw)