cryptodataapi-com Token Supply API

openapi: 3.2.0
info:
  title: Crypto Data Token Supply API
  description: 'Real-time crypto market intelligence API. Built for AI agents: gasless USDC payments via x402 protocol, one-call onboarding, and 180+ endpoints for prices, derivatives, funding, and sentiment.'
  version: '2026-10-28'
servers:
- url: https://cryptodataapi.com
tags:
- name: Token Supply
paths:
  /api/v1/supply/float:
    get:
      tags:
      - Token Supply
      summary: Get Supply Float
      description: 'Circulating float and dilution overhang for every tracked coin.


        Ranked by **ascending float** — the tightest floats first, because that is

        the end of the distribution where supply is the story. A coin trading at a

        23% float with three times its market cap still locked is a different

        instrument from one that is fully distributed.


        - `float_pct` (0..1) — circulating ÷ `supply_basis`.

        - `supply_basis` — **which denominator was used**: `max_supply` when the token

        is genuinely capped, else `total_supply`. `max_supply` is absent for over

        half the universe, and "share of max" and "share of total" are different

        claims, so this is stated rather than assumed.

        - `locked_supply` / `locked_usd` — what is not yet circulating.

        - `dilution_overhang` — locked value as a multiple of current market cap.

        - `next_unlock` — the soonest dated cliff, with same-day tranches summed and

        priced (`usd`, `pct_of_float`, `pct_of_market_cap`).

        - `unlock_coverage` — `tracked` or `not_tracked`. **A null `next_unlock` with

        `not_tracked` does NOT mean the token has no unlock scheduled**; it means

        no schedule is published for it in our source. Do not read it as "safe".


        Defaults to a **$500M market-cap floor**: below it a "tight float" is usually

        a nominal `total_supply` rather than a real vesting schedule, and those

        artifacts otherwise dominate the top of an ascending-float ranking. Pass

        `min_market_cap=0` for the unfiltered set — the rows are still computed, they

        are just not what the default board is for.


        Free tier returns the top 25 rows; Pro and above get the full board and the

        filters.'
      operationId: get_supply_float_api_v1_supply_float_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: min_market_cap
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Market-cap floor. Defaults to $500M because below it a tight float is usually a nominal total_supply rather than a vesting schedule. Pass 0 for the full set.
          default: 500000000.0
          title: Min Market Cap
        description: Market-cap floor. Defaults to $500M because below it a tight float is usually a nominal total_supply rather than a vesting schedule. Pass 0 for the full set.
      - name: min_locked_usd
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Only rows with at least this much locked value
          default: 0.0
          title: Min Locked Usd
        description: Only rows with at least this much locked value
      - name: max_float_pct
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          exclusiveMinimum: 0
          description: Only rows at or below this float (0-1)
          default: 1.0
          title: Max Float Pct
        description: Only rows at or below this float (0-1)
      - name: symbol
        in: query
        required: false
        schema:
          description: Filter to one ticker
          title: Symbol
          type:
          - string
          - 'null'
        description: Filter to one ticker
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 2000
          minimum: 1
          default: 250
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplyFloatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/supply/unlocks:
    get:
      tags:
      - Token Supply
      summary: Get Supply Unlocks
      description: 'The forward token-unlock calendar — dated vesting cliffs.


        Sourced from DefiLlama''s free emissions data and sized against the coin''s own

        float, so a cliff reads as "12% of circulating supply on 1 Sept" rather than

        a raw token count.


        **This is a cliff calendar, not an emissions feed.** Continuous emission is

        deliberately excluded: mining inflation, linear vesting, and runs of

        identical daily releases are a drip, not a step, and publishing them as

        catalysts buries the real ones. Coverage is bounded by the protocols

        DefiLlama tracks — absence here is not evidence that a token has no unlock.


        Free tier is limited to the next 7 days; Pro and above get the full horizon. Each coin

        lists its SOONEST cliff only. ``limit`` (added 2026-10-10; it used to be ignored) caps

        the rows; an unrecognised query parameter is a 400.'
      operationId: get_supply_unlocks_api_v1_supply_unlocks_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: window_days
        in: query
        required: false
        schema:
          type: integer
          maximum: 35
          minimum: 1
          description: Forward horizon
          default: 30
          title: Window Days
        description: Forward horizon
      - name: symbol
        in: query
        required: false
        schema:
          description: Filter to one ticker. A Hyperliquid k-name (kBONK) finds BONK.
          title: Symbol
          type:
          - string
          - 'null'
        description: Filter to one ticker. A Hyperliquid k-name (kBONK) finds BONK.
      - name: limit
        in: query
        required: false
        schema:
          description: At most this many rows, soonest first
          title: Limit
          type:
          - integer
          - 'null'
          maximum: 500
          minimum: 1
        description: At most this many rows, soonest first
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplyUnlocksResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SupplyFloatRow:
      properties:
        symbol:
          type: string
          title: Symbol
        name:
          type: string
          title: Name
        coingecko_id:
          title: Coingecko Id
          type:
          - string
          - 'null'
        market_cap:
          title: Market Cap
          type:
          - number
          - 'null'
        market_cap_rank:
          title: Market Cap Rank
          type:
          - integer
          - 'null'
        price:
          title: Price
          type:
          - number
          - 'null'
        circulating_supply:
          type: number
          title: Circulating Supply
        total_supply:
          title: Total Supply
          type:
          - number
          - 'null'
        max_supply:
          title: Max Supply
          type:
          - number
          - 'null'
        supply_basis:
          type: string
          enum:
          - max_supply
          - total_supply
          title: Supply Basis
        float_pct:
          type: number
          title: Float Pct
        locked_supply:
          type: number
          title: Locked Supply
        locked_usd:
          title: Locked Usd
          type:
          - number
          - 'null'
        dilution_overhang:
          title: Dilution Overhang
          type:
          - number
          - 'null'
        next_unlock:
          $ref: '#/components/schemas/NextUnlock'
        unlock_coverage:
          type: string
          enum:
          - tracked
          - not_tracked
          title: Unlock Coverage
        rank:
          type: integer
          title: Rank
      type: object
      required:
      - symbol
      - name
      - circulating_supply
      - supply_basis
      - float_pct
      - locked_supply
      - unlock_coverage
      - rank
      title: SupplyFloatRow
      description: One coin's supply state.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    NextUnlock:
      properties:
        date:
          type: string
          title: Date
        timestamp_ms:
          type: integer
          title: Timestamp Ms
        days_until:
          type: integer
          title: Days Until
        tokens:
          title: Tokens
          type:
          - number
          - 'null'
        usd:
          title: Usd
          type:
          - number
          - 'null'
        pct_of_float:
          title: Pct Of Float
          type:
          - number
          - 'null'
        pct_of_market_cap:
          title: Pct Of Market Cap
          type:
          - number
          - 'null'
        categories:
          items:
            type: string
          type: array
          title: Categories
          default: []
      type: object
      required:
      - date
      - timestamp_ms
      - days_until
      title: NextUnlock
      description: The soonest dated cliff for a coin, same-day tranches summed.
    SupplyUnlockItem:
      properties:
        symbol:
          type: string
          title: Symbol
        name:
          type: string
          title: Name
        coingecko_id:
          title: Coingecko Id
          type:
          - string
          - 'null'
        date:
          type: string
          title: Date
        days_until:
          type: integer
          title: Days Until
        tokens:
          title: Tokens
          type:
          - number
          - 'null'
        usd:
          title: Usd
          type:
          - number
          - 'null'
        pct_of_float:
          title: Pct Of Float
          type:
          - number
          - 'null'
        pct_of_market_cap:
          title: Pct Of Market Cap
          type:
          - number
          - 'null'
        categories:
          items:
            type: string
          type: array
          title: Categories
          default: []
        float_pct:
          type: number
          title: Float Pct
        market_cap:
          title: Market Cap
          type:
          - number
          - 'null'
      type: object
      required:
      - symbol
      - name
      - date
      - days_until
      - float_pct
      title: SupplyUnlockItem
    SupplyUnlocksResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SupplyUnlockItem'
          type: array
          title: Items
        count:
          type: integer
          title: Count
        window_days:
          type: integer
          title: Window Days
        tier_scope:
          type: string
          title: Tier Scope
        as_of:
          type: string
          title: As Of
      type: object
      required:
      - items
      - count
      - window_days
      - tier_scope
      - as_of
      title: SupplyUnlocksResponse
    SupplyFloatResponse:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/SupplyFloatRow'
          type: array
          title: Rows
        count:
          type: integer
          title: Count
        summary:
          $ref: '#/components/schemas/SupplyFloatSummary'
        tier_scope:
          type: string
          title: Tier Scope
        as_of:
          type: string
          title: As Of
      type: object
      required:
      - rows
      - count
      - summary
      - tier_scope
      - as_of
      title: SupplyFloatResponse
    SupplyFloatSummary:
      properties:
        coins:
          type: integer
          title: Coins
        total_locked_usd:
          title: Total Locked Usd
          type:
          - number
          - 'null'
        median_float_pct:
          title: Median Float Pct
          type:
          - number
          - 'null'
        tight_float_count:
          type: integer
          title: Tight Float Count
        with_tracked_unlock:
          type: integer
          title: With Tracked Unlock
        notable_overhang:
          type: integer
          title: Notable Overhang
      type: object
      required:
      - coins
      - tight_float_count
      - with_tracked_unlock
      - notable_overhang
      title: SupplyFloatSummary
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key