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

# Balances

> Holder balances on any past date, computed at query time.

Balances are not stored anywhere. Two functions in the `functions` dataset compute them at query time from [Balance changes](/docs/catalog/tokens/balance-changes), adding up every change recorded for one token. Each takes a chain, a token address and a token standard.

## Functions

<Tabs>
  <Tab title="Latest">
    `functions.calculate_latest_token_balances` returns everyone holding the token right now: the last end-of-day balance per account, positive balances only. An account that sent everything away falls out rather than appearing at zero.

    <table>
      <thead>
        <tr>
          <th width="280">Parameter</th>
          <th width="130">Type</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>p\_chain\_id</code></td>
          <td><code>STRING</code></td>
          <td>Chain the token is deployed on, for example <code>ethereum</code>.</td>
        </tr>

        <tr>
          <td><code>p\_token\_address</code></td>
          <td><code>STRING</code></td>
          <td>Contract address of the token.</td>
        </tr>

        <tr>
          <td><code>p\_token\_type</code></td>
          <td><code>STRING</code></td>
          <td>Token standard, such as <code>erc20</code>.</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th width="280">Return column</th>
          <th width="130">Type</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>account\_address</code></td>
          <td><code>STRING</code></td>
          <td>Account holding a positive balance.</td>
        </tr>

        <tr>
          <td><code>balance</code></td>
          <td><code>BIGNUMERIC</code></td>
          <td>Latest end-of-day balance in token units.</td>
        </tr>
      </tbody>
    </table>

    The order of the two steps matters. The function takes each account's most recent row first, then drops the accounts sitting at zero. In the other order, an account that has since sent everything away comes back showing its last positive balance.
  </Tab>

  <Tab title="Historical">
    `functions.calculate_historical_eod_token_balances` returns each holder's end-of-day balance, one row per day the balance moved. There is no row for a day when nothing moved: an account that moved tokens on Monday and again on Friday has two rows and nothing in between, and its balance on Wednesday is whatever the Monday row says. Reading a balance for a given date means taking the most recent row at or before that date.

    <table>
      <thead>
        <tr>
          <th width="280">Parameter</th>
          <th width="130">Type</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>p\_chain\_id</code></td>
          <td><code>STRING</code></td>
          <td>Chain the token is deployed on, for example <code>ethereum</code>.</td>
        </tr>

        <tr>
          <td><code>p\_token\_address</code></td>
          <td><code>STRING</code></td>
          <td>Contract address of the token.</td>
        </tr>

        <tr>
          <td><code>p\_token\_type</code></td>
          <td><code>STRING</code></td>
          <td>Token standard, such as <code>erc20</code>.</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th width="280">Return column</th>
          <th width="130">Type</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>balance\_date</code></td>
          <td><code>DATE</code></td>
          <td>Day the balance moved.</td>
        </tr>

        <tr>
          <td><code>account\_address</code></td>
          <td><code>STRING</code></td>
          <td>Account holding the balance.</td>
        </tr>

        <tr>
          <td><code>balance</code></td>
          <td><code>BIGNUMERIC</code></td>
          <td>End-of-day balance in token units, scaled down by <code>decimals</code>.</td>
        </tr>
      </tbody>
    </table>
  </Tab>
</Tabs>

## Sample queries

<Warning>
  Each call adds up the entire balance-change history of one token. For a daily supply or holder-count series, the [daily asset tables](/docs/catalog/assets/metrics) carry both for curated assets.
</Warning>

<Tabs>
  <Tab title="Current holders">
    **List the current holders of one token.**

    ```sql theme={null}
    select
        account_address,
        balance
    from `functions.calculate_latest_token_balances`(
        'ethereum',
        '0xdac17f958d2ee523a2206206994597c13d831ec7',
        'erc20'
    )
    order by balance desc
    limit 100
    ```
  </Tab>

  <Tab title="Holders on a date">
    **List the holders of one token on a past date.** The most recent row at or before the date is the balance on that date, and accounts at zero are dropped after that row is picked.

    ```sql theme={null}
    with balances_on_date as (
        select
            account_address,
            balance,
            row_number() over (partition by account_address order by balance_date desc) as recency
        from `functions.calculate_historical_eod_token_balances`(
            'ethereum',
            '0xdac17f958d2ee523a2206206994597c13d831ec7',
            'erc20'
        )
        where balance_date <= date '2026-06-30'
    )

    select
        account_address,
        balance
    from balances_on_date
    where recency = 1
      and balance > 0
    order by balance desc
    limit 100
    ```
  </Tab>
</Tabs>

## Notes

Address matching follows the chain's own rules. EVM addresses are case-insensitive: they are stored lowercase and both functions lowercase their inputs, so a checksummed address copied from an explorer resolves. Solana addresses are base58 and case-sensitive: they are stored and matched verbatim.

Balances are added up in exact whole-number arithmetic and scaled by the token's `decimals`, so a drained account reads exactly zero and is not counted as a holder.