---
title: "Token - Holder Positions"
method: GET
path: "/token/v1/holder-positions"
tags: ["Holder"]
---

# Token - Holder Positions

`GET /token/v1/holder-positions`

Retrieve a paginated list of wallet positions for a specified token, filtered by holder tags. Returns per-wallet trading data including PnL, volumes, and associated labels.

## Query parameters

- `token_address` string, required
- `labels` string[]
- `sort_by` 'amount'
- `order_type` 'asc' | 'desc'
- `ui_amount_mode` 'scaled' | 'raw'
- `include_zero_balance` boolean
- `offset` integer
- `limit` integer

## Headers

- `x-chain` 'solana'

## Response `200`

JSON array containing token holder position details

- TokenHolderPositionResponse
  - `success` boolean, required — Whether the request succeeded.
  - `data` object[], required — Wallet positions matching the requested labels, one entry per wallet.
    - `wallet_address` string — Holder wallet address
    - `hold_amount` string — Token amount currently held by this wallet
    - `percent_of_supply` number — Percentage of total supply held by this wallet
    - `buy_volume` string — Total token buy volume of this wallet
    - `sell_volume` string — Total token sell volume of this wallet
    - `buy_volume_usd` string — Total buy volume in USD of this wallet
    - `sell_volume_usd` string — Total sell volume in USD of this wallet
    - `avg_buy_price` string — Average buy price in USD of this wallet
    - `pnl` string — Total PnL in USD for this wallet, realized and unrealized combined
    - `buy_count` integer — Number of buy transactions made by this wallet
    - `sell_count` integer — Number of sell transactions made by this wallet
    - `first_trade_at` string, date-time — Timestamp of this wallet's first trade on the token (ISO 8601, UTC)
    - `labels` string[] — Labels associated with this wallet for the given token. Supported labels: `bundler`, `sniper`, `insider`, `dev`, `smart_trader`.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. API key is missing or invalid
- `403` — Forbidden. Request is blacklisted or not whitelisted
- `429` — Too Many Requests. Rate limit reached
- `500` — Internal Server Error

---

[API](https://skmtc.net/birdeye/apis/birdeye-data-api.md) · [All operations](https://skmtc.net/birdeye/apis/birdeye-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/birdeye/birdeye-data-api/revisions/fcaba926a089/schema)