> ## 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.

# Liquidity History - Token

> A historical liquidity time-series API for Solana tokens, returning snapshot liquidity data from the open value of each liquidity candle. Supports 1m, 4h, and 1D resolutions. Maximum 100 records.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Historical token liquidity snapshots on Solana.</strong></p>

    <ul>
      <li>This endpoint returns snapshot liquidity values from the open of each liquidity candle rather than full OHLC candle structure.</li>
      <li>Supported <code>resolution</code> values are <code>1m</code>, <code>4h</code>, and <code>1D</code>.</li>
      <li>Maximum <code>count</code> is <code>100</code> records per request.</li>
      <li>Historical liquidity data is available from January 1, 2024 onward.</li>
    </ul>
  </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>CU is dynamic by resolution: base <code>20 CU</code> for <code>1m</code>, <code>50 CU</code> for <code>4h</code>, <code>200 CU</code> for <code>1D</code>, with depth and lookback multipliers applied.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Build a clean liquidity time series without needing full OHLC candle fields.</li>
    <li>Track how token depth changed across launches, incentives, or LP exits.</li>
    <li>Support risk, treasury, and market-health dashboards focused on liquidity levels.</li>
    <li>Join liquidity history with price, holder, or smart-money timelines for richer narratives.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Set <code>x-chain=solana</code>.</li>
    <li>Pass the token mint in <code>address</code>.</li>
    <li>Choose <code>resolution</code> and page with <code>time</code>, <code>direction</code>, and <code>count</code>.</li>
    <li>Use the OHLC token liquidity endpoint instead when you need open/high/low/close structure, not just snapshots.</li>
  </ul>
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  <ul>
    <li>Prefer this endpoint over OHLC liquidity when the consumer only needs level snapshots.</li>
    <li>Align liquidity history windows with the same resolution used by your price or holder charts.</li>
    <li>Use coarser resolutions for multi-week or multi-month views to avoid over-dense series.</li>
  </ul>
</Accordion>

<Accordion title="Limitations ⚠️" icon="fa-exclamation-triangle">
  <ul>
    <li>Solana only.</li>
  </ul>
</Accordion>

<br />


## OpenAPI

````yaml openapi/data/openapi_docs.json GET /defi/v3/liquidity/history/token
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:
  /defi/v3/liquidity/history/token:
    get:
      tags:
        - Price & OHLCV
      summary: Liquidity History - Token
      description: >-
        A historical liquidity time-series API for Solana tokens, returning
        snapshot liquidity data from the open value of each liquidity candle.
        Supports 1m, 4h, and 1D resolutions. Maximum 100 records.
      operationId: get-defi-v3-liquidity-history-token
      parameters:
        - $ref: '#/components/parameters/xSolanaChainParam'
        - $ref: '#/components/parameters/tokenAddressParam'
        - $ref: '#/components/parameters/liquidityOhlcResolutionParam'
        - $ref: '#/components/parameters/liquidityOhlcTimeParam'
        - $ref: '#/components/parameters/liquidityOhlcDirectionParam'
        - $ref: '#/components/parameters/liquidityOhlcCountParam'
      responses:
        '200':
          $ref: '#/components/responses/DefiLiquidityHistoryToken'
        '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
    tokenAddressParam:
      name: address
      description: The address of the token contract.
      in: query
      required: true
      schema:
        type: string
      examples:
        wsol:
          value: So11111111111111111111111111111111111111112
        solana:
          value: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
        ethereum:
          value: '0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce'
        solana_scaled_ui:
          value: Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh
    liquidityOhlcResolutionParam:
      name: resolution
      description: Liquidity candle resolution.
      in: query
      required: false
      schema:
        type: string
        enum:
          - 1m
          - 4h
          - 1D
        default: 1m
    liquidityOhlcTimeParam:
      name: time
      description: >-
        Unix timestamp in seconds used as the anchor time for the liquidity
        candle window. Defaults to the latest available candle.
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000000000
      example: 1750950840
    liquidityOhlcDirectionParam:
      name: direction
      description: >-
        Direction to query candles from the anchor time. Use back for older
        candles and forward for newer candles.
      in: query
      required: false
      schema:
        type: string
        enum:
          - back
          - forward
        default: back
      example: back
    liquidityOhlcCountParam:
      name: count
      description: >-
        Maximum number of liquidity candles returned. Defaults to 100 and is
        capped at 100.
      in: query
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 100
      example: 100
  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
    DefiLiquidityHistoryToken:
      description: JSON object containing historical liquidity snapshots of a token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DefiLiquidityHistoryTokenResponse'
          examples:
            Solana:
              value:
                success: true
                data:
                  items:
                    - unix_time: 1778112000
                      liquidity_usd: 76897848464.11568
                      exit_liquidity_usd: 76315406.4596759
                      stable_liquidity_usd: 79315782724.2839
                      total_pairs: 11782972
                  direction: prev
                  limit: 100
                  next_cursor: null
                  prev_cursor: 1778097600
                  has_more: true
  schemas:
    DefiLiquidityHistoryTokenResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request completed successfully.
        data:
          type: object
          description: Historical liquidity snapshots for the requested token.
          required:
            - items
            - direction
            - limit
            - next_cursor
            - prev_cursor
            - has_more
          properties:
            items:
              type: array
              description: Historical liquidity points ordered by timestamp.
              items:
                type: object
                required:
                  - unix_time
                  - liquidity_usd
                  - exit_liquidity_usd
                  - stable_liquidity_usd
                  - total_pairs
                properties:
                  unix_time:
                    type: integer
                    description: Unix timestamp in seconds for this liquidity snapshot.
                  liquidity_usd:
                    type: number
                    description: Total token liquidity in USD at this timestamp.
                  exit_liquidity_usd:
                    type: number
                    description: Estimated exit liquidity in USD at this timestamp.
                  stable_liquidity_usd:
                    type: number
                    description: >-
                      Liquidity in USD at this timestamp across pools paired
                      with top coins, counting both sides of each pool.
                  total_pairs:
                    type: integer
                    description: >-
                      Number of token pairs contributing to the liquidity
                      snapshot.
            direction:
              type: string
              enum:
                - next
                - prev
              description: >-
                Internal cursor direction returned for the current result
                window.
            limit:
              type: integer
              description: >-
                Number of history points requested from the upstream liquidity
                data service.
            next_cursor:
              type: integer
              nullable: true
              description: Unix timestamp cursor for the next page of newer history points.
            prev_cursor:
              type: integer
              nullable: true
              description: >-
                Unix timestamp cursor for the previous page of older history
                points.
            has_more:
              type: boolean
              description: Whether another page is available in the returned direction.
    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

````