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

# Token - Tag Holdings Chart

> Retrieve timestamped holder and holding data grouped by Solana holder tag type. Each tag returns up to 100 chart points.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Holder and holding trends grouped by wallet tag.</strong></p>

    <ul>
      <li><code>tag\_type</code> supports <code>bundler</code> and <code>sniper</code>. Omit it to return all supported tag series.</li>
      <li><code>chart\_type</code> controls the time interval and supports <code>1d</code>, <code>1h</code>, and <code>1m</code>.</li>
      <li><code>time\_from</code> and <code>time\_to</code> are unix timestamps in seconds. <code>time\_to</code> defaults to now.</li>
      <li>Each tag series contains timestamped points with <code>total\_holder</code>, <code>total\_holding</code>, and <code>time</code>.</li>
    </ul>

    <p><strong>Reading the numbers.</strong> <code>total\_holder</code> is the number of wallets with the tag that hold the token at that point. <code>total\_holding</code> is the token amount held by that tagged cohort.</p>
  </Tab>

  <Tab title="Accessibility">
    <ul>
      <li>Lite</li>
      <li>Starter</li>
      <li>Premium</li>
      <li>Business</li>
      <li>Enterprise</li>
    </ul>
  </Tab>

  <Tab title="Chain Supported">
    <p><strong>Solana</strong></p>
  </Tab>
</Tabs>

<Accordion title="Compute Unit ⚙️" icon="fa-gauge-high">
  <ul>
    <li>This endpoint consumes <code>20 CU</code> per request.</li>
  </ul>
</Accordion>

<Accordion title="Wallet Tag Definitions 🏷️" icon="fa-tags">
  <ul>
    <li><strong>dev</strong> — The wallet that created the token: the mint creator from the initialize-mint transaction.</li>
  </ul>

  <ul>
    <li><strong>sniper</strong> — A wallet that bought within the first <code>n</code> blocks of the token, counted from the token's first swap. On Solana, <code>n = 5</code>; a buy qualifies when its slot is within <code>first\_trade\_slot + 5</code>.</li>
  </ul>

  <ul>
    <li><strong>bundler</strong> — Coordinated buying detected in either level:</li>
    <li>Level 1: at least 4 buy transactions in the same slot.</li>
    <li>Level 2: at least 3 distinct wallets buying across adjacent slots, where max slot gap is 1.</li>
  </ul>

  <ul>
    <li><strong>insider</strong> — A wallet that received the token directly from the Chef wallet via token transfer, not via a swap.</li>
  </ul>

  <ul>
    <li><strong>smart\_trader</strong> — A non-bot wallet ranked in Top Realized PnL over the last 90 days with realized PnL > \$10,000. Wallets identified as bots are excluded before ranking and never receive this tag.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Turn holder labels into a living time series: watch bundler and sniper cohorts expand, shrink, accumulate, or distribute over time.</li>
    <li>Build launch-quality charts that show whether suspicious early cohorts are still holding meaningful supply after trading begins.</li>
    <li>Detect changing risk posture when tagged holder count falls while tagged holding remains high, or when holding drops sharply across a short window.</li>
    <li>Pair tag holdings with price and volume charts to understand whether labeled wallets are supporting momentum or selling into demand.</li>
    <li>Create narrative research panels that show how token ownership evolves from launch concentration toward broader or riskier distribution.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Provide a Solana <code>token\_address</code>.</li>
    <li>Choose <code>chart\_type=1m</code>, <code>1h</code>, or <code>1d</code> based on the granularity you need.</li>
    <li>Use <code>tag\_type=bundler</code>, <code>tag\_type=sniper</code>, or omit <code>tag\_type</code> to return all supported tags.</li>
    <li>Use <code>time\_from</code> and <code>time\_to</code> to focus on a launch window, volatility event, or post-launch period.</li>
    <li>Plot <code>total\_holder</code> and <code>total\_holding</code> together to see both cohort size and token exposure.</li>
  </ul>
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  <ul>
    <li>Compare holder count and holding amount together; a small holder count with high holding can signal concentrated tagged exposure.</li>
    <li>Align tag-holding changes with price and volume candles to see whether tagged cohorts accumulated before momentum or distributed into demand.</li>
    <li>Use this endpoint for time-series cohort behavior, then use holder-positions when you need the exact wallets.</li>
    <li>Keep the chart window focused; shorter windows make launch and exit patterns easier to interpret.</li>
  </ul>
</Accordion>

<Accordion title="Limitations ⚠️" icon="fa-exclamation-triangle">
  <ul>
    <li>Solana only.</li>
    <li>Supported <code>tag\_type</code> values are <code>bundler</code> and <code>sniper</code>.</li>
    <li>Supported <code>chart\_type</code> values are <code>1d</code>, <code>1h</code>, and <code>1m</code>.</li>
    <li>Each tag returns up to 100 chart points.</li>
    <li>This endpoint returns tagged cohort trends, not individual wallet-level positions.</li>
  </ul>
</Accordion>

<br />


## OpenAPI

````yaml openapi/data/openapi_docs.json GET /token/v1/chart/tag-holdings
openapi: 3.1.0
info:
  version: 1.1.0
  title: Birdeye Data API
  description: >-
    Birdeye Data API is a full-spectrum blockchain and DEX data platform for
    teams that need production-grade crypto market intelligence across tokens,
    pairs, wallets, traders, protocols, and chains.


    From real-time prices, OHLCV, liquidity, and transaction flow to holder
    analytics, token and pair overviews, wallet portfolio and PnL, smart money,
    discovery, security, and blockchain-level utilities, Birdeye gives you a
    unified data layer for building serious crypto products at scale.


    Use it to power exchange interfaces, trading terminals, bots, market-making
    systems, quant research, alpha screeners, portfolio apps, wallet
    intelligence tools, alerting systems, analytics dashboards, and back-office
    data pipelines. Whether your users are retail traders, pro desks, analysts,
    or infrastructure teams, Birdeye helps you ship faster with broad market
    coverage and API surfaces that support both lightweight integrations and
    data-heavy workflows.


    To start, create an account at [bds.birdeye.so](https://bds.birdeye.so),
    generate an API key from the `Security` tab, and send it in the `X-API-KEY`
    header on every request.
servers:
  - url: https://public-api.birdeye.so
security:
  - apiKeyAuth: []
tags:
  - name: Price & OHLCV
  - name: Stats
  - name: Token/Market List
  - name: Transactions
  - name: Wallet, Networth & PnL
  - name: Balance & Transfer
  - name: Holder
  - name: Alltime & History
  - name: Blockchain
  - name: Account
  - name: Token
  - name: Transaction
  - name: Creation & Trending
  - name: Meme
  - name: Security
  - name: Search & Utils
  - name: Smart Money
  - name: Global Fees Paid
  - name: DEX & Protocol
  - name: Wallet Identity
paths:
  /token/v1/chart/tag-holdings:
    get:
      tags:
        - Holder
      summary: Token - Tag Holdings Chart
      description: >-
        Retrieve timestamped holder and holding data grouped by Solana holder
        tag type. Each tag returns up to 100 chart points.
      operationId: get-token-v1-chart-tag-holdings
      parameters:
        - $ref: '#/components/parameters/xSolanaChainParam'
        - $ref: '#/components/parameters/tokenHolderTagChartTokenAddressParam'
        - $ref: '#/components/parameters/optionalChartTagHolderType'
        - $ref: '#/components/parameters/optionalHolderTagType'
        - $ref: '#/components/parameters/optionalChartTagHolderTimeFrom'
        - $ref: '#/components/parameters/optionalChartTagHolderTimeTo'
      responses:
        '200':
          $ref: '#/components/responses/ChartTagHolderResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    xSolanaChainParam:
      name: x-chain
      description: Solana network only.
      in: header
      required: false
      schema:
        type: string
        enum:
          - solana
        default: solana
    tokenHolderTagChartTokenAddressParam:
      name: token_address
      description: Token contract address.
      in: query
      required: true
      schema:
        type: string
      examples:
        solana:
          value: J3Dhvhga7QwgLWUGn43caDJtaoUTkDLmiMGqstS2Dw8A
    optionalChartTagHolderType:
      name: chart_type
      description: 'Chart interval: 1d, 1h, 1m.'
      in: query
      required: false
      schema:
        type: string
        enum:
          - 1d
          - 1h
          - 1m
        default: 1d
    optionalHolderTagType:
      name: tag_type
      description: >-
        Comma-separated holder tag types. Omit to return all supported tag
        types.
      in: query
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - bundler
            - sniper
        default:
          - bundler
          - sniper
        example:
          - bundler
          - sniper
    optionalChartTagHolderTimeFrom:
      name: time_from
      description: >-
        Start time using unix timestamp in seconds. Defaults to 3 months before
        the current time.
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000000000
    optionalChartTagHolderTimeTo:
      name: time_to
      description: End time using unix timestamp in seconds. Defaults to the current time.
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000000000
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Bad request
    '401':
      description: Unauthorized. API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Unauthorized
    '403':
      description: Forbidden. Request is blacklisted or not whitelisted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Access Denied
    '429':
      description: Too Many Requests. Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Too many requests
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Internal Server Error
    ChartTagHolderResponse:
      description: JSON object containing holder chart data grouped by tag type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ChartTagHoldingsResponse'
          examples:
            solana:
              value:
                data:
                  bundler:
                    - total_holder: 2
                      total_holding: 0.000002
                      time: 1700697600
                  sniper:
                    - total_holder: 1
                      total_holding: 0
                      time: 1700697600
                success: true
  schemas:
    ChartTagHoldingsResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          type: object
          description: >-
            Holder time series grouped by holder tag type. Each key is a tag
            type and maps to its time series. Supported tag types: `bundler`,
            `sniper`. Only the tag types requested via the tag_type parameter
            are returned.
          properties:
            bundler:
              type: array
              description: >-
                Holder time series for a single tag type, ordered from newest to
                oldest.
              items:
                type: object
                description: A single data point in the holder time series for a tag type.
                properties:
                  total_holder:
                    type: integer
                    description: >-
                      Number of wallets carrying this tag that hold the token at
                      this data point.
                  total_holding:
                    type: number
                    description: >-
                      Total token amount held by the tagged wallets at this data
                      point.
                  time:
                    type: integer
                    description: >-
                      Start time of the data point as a unix timestamp in
                      seconds.
            sniper:
              type: array
              description: >-
                Holder time series for a single tag type, ordered from newest to
                oldest.
              items:
                type: object
                description: A single data point in the holder time series for a tag type.
                properties:
                  total_holder:
                    type: integer
                    description: >-
                      Number of wallets carrying this tag that hold the token at
                      this data point.
                  total_holding:
                    type: number
                    description: >-
                      Total token amount held by the tagged wallets at this data
                      point.
                  time:
                    type: integer
                    description: >-
                      Start time of the data point as a unix timestamp in
                      seconds.
          additionalProperties:
            type: array
            description: >-
              Holder time series for a single tag type, ordered from newest to
              oldest.
            items:
              type: object
              description: A single data point in the holder time series for a tag type.
              properties:
                total_holder:
                  type: integer
                  description: >-
                    Number of wallets carrying this tag that hold the token at
                    this data point.
                total_holding:
                  type: number
                  description: >-
                    Total token amount held by the tagged wallets at this data
                    point.
                time:
                  type: integer
                  description: Start time of the data point as a unix timestamp in seconds.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````