---
title: "Get token holders with query filtering"
method: GET
path: "/v1/holders"
tags: ["holders"]
---

# Get token holders with query filtering

`GET /v1/holders`

## Request

- Base URL: `https://lpad-backend.stage.defi.ovh.gala.com`
- URL: `https://lpad-backend.stage.defi.ovh.gala.com/v1/holders`
- Auth: none declared
- TypeScript: <https://skmtc.dev/gala/apis/launchpad-backend-api/docs/v1/holders/get.ts> (a function with typed inputs; its response is checked against the schema)

Get top token holders or specific user holder data using query parameters

## Query parameters

- `pageSize` unknown
- `userAddress` string
- `tokenName` string, required

## Response `200`

Holder data retrieved successfully - returns array of top holders or specific user data

- union
  - HolderListSuccessEnvelopeDto
    - `data` HolderItemResponseDto[], required
      - `owner` string, required: Wallet address as returned by the holder service.
      - `quantity` string, required: Token quantity, represented as a decimal string.
    - `error` false, required
    - `message` string, required
    - `status` number, required
  - UserHolderSuccessEnvelopeDto
    - `data` UserHolderResponseDto, required
      - `holderTier` union, required
        - HolderTierResponseDto
          - `tier` 0 | 1 | 2 | 3 | 4 | 5, required
          - `tierName` string, required
        - unknown
      - `isCreator` boolean, required
      - `percentage` number, nullable, required
      - `quantity` string, nullable, required
      - `rank` number, nullable, required
      - `tokenName` string, required
      - `userAddress` string, required
    - `error` false, required
    - `message` string, required
    - `status` number, required

## Other responses

- `400`: Bad request - invalid query parameters or tokenName format
- `404`: Token not found - tokenName does not match any existing pool
- `500`: Internal server error - failed to retrieve holder data from blockchain or cache
- `default`: Shared error envelope for token lookup and holder service failures.

---

[API](https://skmtc.dev/gala/apis/launchpad-backend-api.md) - [All operations](https://skmtc.dev/gala/apis/launchpad-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gala/apis/launchpad-backend-api/revisions/74545971be2b?raw)