> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 토큰 - 홀더

> 토큰 홀더 조회

<Note>
  토큰 홀더 목록과 잔액을 가져옵니다. 상위 홀더만 필요하다면 `topHolders` 엔드포인트를 사용하세요.
</Note>

**관련**: [GraphQL 홀더](/ko/graphql/examples/balance-holders) | MCP: `token_get_holders`


## OpenAPI

````yaml /ko/api-reference/openapi-data-ko.yaml GET /v2/token/{chain}/{tokenAddress}/holders
openapi: 3.1.0
info:
  title: Services API
  description: Services API
  contact:
    name: AI
    email: ai@sx.ai
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.chainstream.io
    description: Production
security:
  - bearer_auth: []
  - api_key_auth: []
tags:
  - name: Blockchain
    description: 블록체인 관련 작업
  - name: Token
    description: 토큰 관련 작업
  - name: Trade
    description: 거래 관련 작업
  - name: Wallet
    description: 지갑 관련 작업
  - name: Dex
    description: DEX 관련 작업
  - name: Ranking
    description: 랭킹 관련 작업
  - name: DexPool
    description: DEX 풀 관련 작업
  - name: Watchlist
    description: 워치리스트 관련 작업
  - name: KYT
    description: KYT 관련 작업
  - name: Webhook
    description: Webhook 관련 작업
  - name: RedPacket
    description: 레드패킷 관련 작업
  - name: IPFS
    description: IPFS 관련 작업
  - name: DexScreener
    description: DexScreener 관련 작업
paths:
  /v2/token/{chain}/{tokenAddress}/holders:
    get:
      tags:
        - Token
      summary: 토큰 - 홀더
      description: 토큰 홀더 조회
      operationId: get.holders
      parameters:
        - name: chain
          in: path
          description: 지원되는 네트워크에 나열된 체인 이름
          required: true
          schema:
            $ref: '#/components/schemas/ChainSymbol'
          example: sol
        - name: tokenAddress
          in: path
          description: 토큰 주소
          required: true
          schema:
            type: string
          example: 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
        - name: cursor
          in: query
          description: 페이지네이션 커서
          required: false
          schema:
            type: string
          example: eyJpZCI6IjEyMyJ9
        - name: limit
          in: query
          description: 페이지당 결과 수
          required: false
          schema:
            type: integer
            format: int64
            default: 20
          example: 20
        - name: direction
          in: query
          description: 페이지네이션 방향 (next 또는 prev)
          required: false
          schema:
            oneOf:
              - $ref: '#/components/schemas/PageDirection'
            default: next
          example: next
        - name: sortBy
          in: query
          description: >-
            DTO.TOKEN.HOLDERS.SORT_BY Sort by: amountPercentage (default) |
            holdingUsd | usdValue | totalPnl | realizedPnl | unrealizedPnl |
            buyVolume | sellVolume | netflowUsd | lastActiveAt | createdAt
          required: false
          schema:
            $ref: '#/components/schemas/HolderSortBy'
          example: amountPercentage
        - name: sortDirection
          in: query
          description: 'Sort direction: desc (default) | asc'
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
          example: desc
        - name: tag
          in: query
          description: >-
            Filter by wallet tag: smart | kol | sniper | dev | bundle | bluechip
            | fresh | insider | pro | sandwich | phishing
          required: false
          schema:
            $ref: '#/components/schemas/TokenTraderTag'
          example: smart
        - name: minCostUsd
          in: query
          description: >-
            Minimum position cost in USD (inclusive). Filters out holders whose
            open position cost is below this threshold.

            Maps to OpenSearch field `position_cost_in_usd`.
          required: false
          schema:
            type: string
          example: '100'
      responses:
        '200':
          description: 홀더 조회
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse_TokenHolder'
components:
  schemas:
    ChainSymbol:
      type: string
      description: Supported blockchain chains
      enum:
        - sol
        - eth
        - bsc
    PageDirection:
      type: string
      description: Pagination direction
      enum:
        - next
        - prev
    HolderSortBy:
      type: string
      description: Sort field for token holders query
      enum:
        - amountPercentage
        - holdingUsd
        - usdValue
        - totalPnl
        - realizedPnl
        - unrealizedPnl
        - buyVolume
        - sellVolume
        - netflowUsd
        - lastActiveAt
        - createdAt
    SortDirection:
      type: string
      description: 'Sort direction (case-insensitive: accepts "asc"/"ASC"/"Asc" etc.)'
      enum:
        - asc
        - desc
    TokenTraderTag:
      type: string
      description: Token trader tag
      enum:
        - smart
        - kol
        - sniper
        - dev
        - bundle
        - bluechip
        - fresh
        - insider
        - pro
        - sandwich
        - phishing
    PageResponse_TokenHolder:
      type: object
      description: Generic pagination response
      required:
        - data
      properties:
        data:
          type: array
          items:
            type: object
            description: Token holder
            required:
              - walletAddress
              - amount
              - amountInUsd
              - percentage
            properties:
              accountAddress:
                type:
                  - string
                  - 'null'
                description: >-
                  Solana token account address (ATA) for this holder position.

                  Distinct from walletAddress (the owner). Matches GMGN
                  `accountAddress`.
              accuAmount:
                type:
                  - string
                  - 'null'
                description: >-
                  Traceable cumulative DEX buy quantity — buy-side only (GMGN:
                  accu_amount)
              accuCost:
                type:
                  - string
                  - 'null'
                description: 'Traceable position accumulated cost, USD (GMGN: accu_cost)'
              addrType:
                type:
                  - integer
                  - 'null'
                format: int64
                description: >-
                  Address type from dexes_dwd.address_labels (1=CEX, 2=MM, 3=VC,
                  4=KOL …). Matches GMGN `addr_type`.
              addressLabel:
                type:
                  - string
                  - 'null'
                description: >-
                  Specific address label (e.g. "Binance Hot Wallet 1"). Matches
                  GMGN `name`.
              amount:
                type: string
                description: 토큰 보유 수량
                example: '1000000000000000000'
              amountInNative:
                type:
                  - string
                  - 'null'
                description: >-
                  Holder's token position value denominated in the chain's
                  native coin (SOL/BNB/ETH).

                  Computed as `price_in_native × amount` using real-time Redis
                  price;

                  falls back to OpenSearch `post_balance_in_native` snapshot
                  when price is unavailable.
              amountInUsd:
                type: string
                description: USD 기준 토큰 보유 가치
                example: '1000000000000000000'
              avgBuyPriceUsd:
                type:
                  - string
                  - 'null'
                description: Average buy price in USD per token (all-time)
              avgCostUsd:
                type:
                  - string
                  - 'null'
                description: Average cost per token in USD (current position cost basis)
              avgSellPriceUsd:
                type:
                  - string
                  - 'null'
                description: Average sell price in USD per token (all-time)
              buyAmountCur:
                type:
                  - string
                  - 'null'
                description: >-
                  Cumulative token quantity bought, all-time (GMGN:
                  buy_amount_cur / history_bought_amount)
              buyVolumeNative:
                type:
                  - string
                  - 'null'
                description: All-time total buy volume in native token
              buyVolumeUsd:
                type:
                  - string
                  - 'null'
                description: All-time total buy volume in USD
              createdAt:
                type:
                  - integer
                  - 'null'
                format: int64
                description: >-
                  Unix timestamp (seconds) when this wallet first appeared
                  on-chain (GMGN: created_at).
              endHoldingAt:
                type:
                  - integer
                  - 'null'
                format: int64
                description: Timestamp when holder fully closed position (ms since epoch)
              exchange:
                type:
                  - string
                  - 'null'
                description: >-
                  Entity/exchange name (e.g. "Binance"). Matches GMGN
                  `exchange`.
              firstBuyTime:
                type:
                  - integer
                  - 'null'
                format: int64
                description: Timestamp of first token purchase (ms since epoch)
              historyBoughtCost:
                type:
                  - string
                  - 'null'
                description: >-
                  Total DEX buy cost including fees, USD (GMGN:
                  history_bought_cost)
              historyBoughtFee:
                type:
                  - string
                  - 'null'
                description: 'Total DEX buy fees, USD (GMGN: history_bought_fee)'
              historySoldFee:
                type:
                  - string
                  - 'null'
                description: 'Total DEX sell fees, USD (GMGN: history_sold_fee)'
              historySoldIncome:
                type:
                  - string
                  - 'null'
                description: 'Total DEX sell income, USD (GMGN: history_sold_income)'
              historyTransferInAmount:
                type:
                  - string
                  - 'null'
                description: >-
                  Cumulative transfer-in token qty (GMGN:
                  history_transfer_in_amount)
              historyTransferInCost:
                type:
                  - string
                  - 'null'
                description: 'Transfer-in USD cost basis (GMGN: history_transfer_in_cost)'
              historyTransferOutAmount:
                type:
                  - string
                  - 'null'
                description: >-
                  Cumulative transfer-out token qty (GMGN:
                  history_transfer_out_amount)
              historyTransferOutFee:
                type:
                  - string
                  - 'null'
                description: >-
                  Total transfer-out fee in USD all-time (GMGN:
                  historyTransferOutFee).
              historyTransferOutIncome:
                type:
                  - string
                  - 'null'
                description: 'Transfer-out USD income (GMGN: history_transfer_out_income)'
              isClosed:
                type:
                  - boolean
                  - 'null'
                description: Whether the token position is fully closed (balance = 0)
              isNew:
                type:
                  - boolean
                  - 'null'
                description: 'Whether the wallet is newly created (GMGN: is_new).'
              isTransferIn:
                type:
                  - boolean
                  - 'null'
                description: >-
                  Position acquired purely via transfers, no DEX buy (GMGN:
                  transfer_in)
              lastActiveAt:
                type:
                  - integer
                  - 'null'
                format: int64
                description: Last active timestamp (ms since epoch)
              lastBlock:
                type:
                  - integer
                  - 'null'
                format: int64
                description: >-
                  Last processed block height for this holder position (GMGN:
                  last_block).
              lossCount:
                type:
                  - integer
                  - 'null'
                format: int64
                description: Number of losing trades (PnL < 0)
              makerTokenTags:
                type: array
                items:
                  type: string
                description: >-
                  Per-token position/behaviour tags derived at query time.

                  Possible values: "top_holder" (rank ≤ 10, first page only),

                  "whale" (holding > $10,000 USD), "diamond_hands" (held > 30
                  days).
              nativeBalance:
                type:
                  - string
                  - 'null'
                description: >-
                  Native chain token balance in lamports (SOL) or wei (EVM), as
                  decimal string.

                  Fetched from RPC with a 10-second Redis cache.
              netflowAmount:
                type:
                  - string
                  - 'null'
                description: 'Net token quantity flow: buys − sells (GMGN: netflow_amount)'
              netflowAmountUsd:
                type:
                  - string
                  - 'null'
                description: 'Net USD flow: buy_usd − sell_usd (from OS netflow_usd)'
              netflowUsd:
                type:
                  - string
                  - 'null'
                description: >-
                  Net USD inflow (buy_volume_usd − sell_volume_usd); positive =
                  net buyer
              percentage:
                type: string
                description: 총 공급 대비 보유 비율
                example: '100'
              positionCostUsd:
                type:
                  - string
                  - 'null'
                description: Current open position cost in USD
              realizedPnlRatio:
                type:
                  - string
                  - 'null'
                description: 'Realized PnL / total_cost ratio (GMGN: realized_pnl)'
              realizedProfit:
                type:
                  - string
                  - 'null'
                description: Realized PnL in USD (all-time)
              roi:
                type:
                  - string
                  - 'null'
                description: >-
                  Return on investment = total_pnl / total_cost_all (e.g. 0.25 =
                  25%)
              sellAmountCur:
                type:
                  - string
                  - 'null'
                description: >-
                  Cumulative token quantity sold, all-time (GMGN:
                  sell_amount_cur / history_sold_amount)
              sellAmountPercentage:
                type:
                  - string
                  - 'null'
                description: >-
                  Sell quantity / buy quantity, capped 0–1 (GMGN:
                  sell_amount_percentage)
              sellVolumeNative:
                type:
                  - string
                  - 'null'
                description: All-time total sell volume in native token
              sellVolumeUsd:
                type:
                  - string
                  - 'null'
                description: All-time total sell volume in USD
              startHoldingAt:
                type:
                  - integer
                  - 'null'
                format: int64
                description: >-
                  Timestamp when holder first acquired the token (ms since
                  epoch)
              tags:
                type: array
                items:
                  type: string
                description: Trader classification tags (e.g. "kol", "smart", "sniper")
              tokenTransferIn:
                description: >-
                  Most recent token transfer-in for this holder on this token
                  (GMGN: token_transfer_in).

                  Contains: amount, amountInUsd, txSignature, from, ts.
              tokenTransferOut:
                description: >-
                  Most recent token transfer-out for this holder on this token
                  (GMGN: token_transfer_out).

                  Contains: amount, amountInUsd, txSignature, to, ts.
              totalBuyCount:
                type:
                  - integer
                  - 'null'
                format: int64
                description: All-time total buy trade count
              totalCostUsd:
                type:
                  - string
                  - 'null'
                description: >-
                  All-time accumulated cost basis in USD (total_cost_all from
                  pnl-sync)
              totalProfit:
                type:
                  - string
                  - 'null'
                description: Total PnL in USD (realized + unrealized)
              totalSellCount:
                type:
                  - integer
                  - 'null'
                format: int64
                description: All-time total sell trade count
              transferInAmount7d:
                type:
                  - string
                  - 'null'
                description: Inbound transfer volume in native token over last 7 days
              transferInCount:
                type:
                  - integer
                  - 'null'
                format: int64
                description: 'Number of token transfer-in events (GMGN: transfer_in_count)'
              transferOutAmount7d:
                type:
                  - string
                  - 'null'
                description: Outbound transfer volume in native token over last 7 days
              transferOutCount:
                type:
                  - integer
                  - 'null'
                format: int64
                description: 'Number of token transfer-out events (GMGN: transfer_out_count)'
              unrealizedPnlRatio:
                type:
                  - string
                  - 'null'
                description: 'Unrealized PnL / total_cost ratio (GMGN: unrealized_pnl)'
              unrealizedProfit:
                type:
                  - string
                  - 'null'
                description: Unrealized PnL in USD (current position)
              walletAddress:
                type: string
                description: 홀더 지갑 주소
                example: '0x1234567890abcdef'
              walletTagV2:
                type:
                  - string
                  - 'null'
                description: >-
                  Global rank tag on this token when sorted by balance (e.g.
                  "TOP1", "TOP2").

                  Only present on the first page of a balance-sorted query (no
                  cursor).
              winCount:
                type:
                  - integer
                  - 'null'
                format: int64
                description: Number of winning trades (PnL > 0)
          description: Page data
        endCursor:
          type:
            - string
            - 'null'
          description: Cursor for the end of current page
          example: eyJpZCI6ImVuZCJ9
        hasNext:
          type: boolean
          description: Whether there is a next page
          example: false
        hasPrev:
          type: boolean
          description: Whether there is a previous page
          example: false
        startCursor:
          type:
            - string
            - 'null'
          description: Cursor for the start of current page
          example: eyJpZCI6InN0YXJ0In0=
        total:
          type:
            - integer
            - 'null'
          format: int64
          description: >-
            Total number of items matching the query (not just the current
            page).

            When `None`, the caller should treat it as unknown
            (backward-compatible).
          example: 564094
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    api_key_auth:
      type: apiKey
      in: header
      name: X-API-KEY

````