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

> ## Agent Instructions
> To query the Token Terminal data catalog, read https://tokenterminal.com/docs/catalog/agents-manual.md first. It is the whole catalog as one page: table naming grammar, key columns, partition and cluster rules, units, additivity, and the tables that are documented but not served yet.
> Never query a catalog table on a time bound alone. Also filter its cluster key, which you read from INFORMATION_SCHEMA.COLUMNS; an empty result means the object is a view, whose pruning contract is on its page. Compute is billed to the caller's own Google Cloud project.

# Liquidations

> Individual perpetual market liquidations.

One row per liquidation fill on a perpetual market, keeping the leg of the party whose position was force-closed. `trade_amount` is the size closed on that fill, and `price` is what it filled at.

## Columns

<table>
  <thead>
    <tr>
      <th width="220">Column</th>
      <th width="130">Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>block\_timestamp</code></td>
      <td><code>TIMESTAMP</code></td>
      <td>Time of the block containing the liquidation fill. Partition column.</td>
    </tr>

    <tr>
      <td><code>block\_number</code></td>
      <td><code>INT64</code></td>
      <td>Number of the block containing the liquidation fill.</td>
    </tr>

    <tr>
      <td><code>transaction\_hash</code></td>
      <td><code>STRING</code></td>
      <td>Hash of the transaction that emitted the forced fill. Shared by every fill of the same liquidation.</td>
    </tr>

    <tr>
      <td><code>trade\_id</code></td>
      <td><code>INT64</code></td>
      <td>Forced-fill identifier on HyperCore; fingerprint of chain, transaction hash and log index on MUX. Part of the row key with <code>block\_timestamp</code>, <code>perp\_market\_id</code>, <code>liquidated\_user\_address</code> and <code>crossed</code>.</td>
    </tr>

    <tr>
      <td><code>perp\_market\_id</code></td>
      <td><code>STRING</code></td>
      <td>Market the position was liquidated in, keyed like <a href="/docs/catalog/perpetuals/registry"><code>dimensions.perp\_markets</code></a>.</td>
    </tr>

    <tr>
      <td><code>interface\_app\_id</code></td>
      <td><code>STRING</code></td>
      <td>The builder credited for the market, read from the registry.</td>
    </tr>

    <tr>
      <td><code>exchange\_app\_id</code></td>
      <td><code>STRING</code></td>
      <td>The venue that force-closed the position. The same liquidation is credited under both app columns, so group by one of them for a total.</td>
    </tr>

    <tr>
      <td><code>token\_id</code></td>
      <td><code>STRING</code></td>
      <td>The market's settlement token, keyed like <a href="/docs/catalog/tokens/registry"><code>dimensions.tokens</code></a>. Null on MUX markets, which accept several collateral tokens.</td>
    </tr>

    <tr>
      <td><code>chain\_id</code></td>
      <td><code>STRING</code></td>
      <td>Chain the liquidation happened on.</td>
    </tr>

    <tr>
      <td><code>project\_id</code></td>
      <td><code>STRING</code></td>
      <td>Project the exchange app belongs to.</td>
    </tr>

    <tr>
      <td><code>liquidated\_user\_address</code></td>
      <td><code>STRING</code></td>
      <td>Account whose position was force-closed. Part of the row key, and a position closed in pieces spans one row per fill under this address.</td>
    </tr>

    <tr>
      <td><code>side</code></td>
      <td><code>STRING</code></td>
      <td>The position that was force-closed: <code>A</code> for a long, <code>B</code> for a short.</td>
    </tr>

    <tr>
      <td><code>crossed</code></td>
      <td><code>BOOL</code></td>
      <td>True on a HyperCore taker leg or a MUX pool liquidation; false on a HyperCore maker leg.</td>
    </tr>

    <tr>
      <td><code>price</code></td>
      <td><code>BIGNUMERIC</code></td>
      <td>Execution price in the settlement token on HyperCore and in USD on MUX.</td>
    </tr>

    <tr>
      <td><code>trade\_amount</code></td>
      <td><code>BIGNUMERIC</code></td>
      <td>Size force-closed on this fill, in units of the underlying asset. Times <code>price</code> it is the liquidated notional in the HyperCore settlement token or in USD on MUX.</td>
    </tr>

    <tr>
      <td><code>mark\_price</code></td>
      <td><code>BIGNUMERIC</code></td>
      <td>Mark price the liquidation was triggered at. Null on MUX executions.</td>
    </tr>

    <tr>
      <td><code>method</code></td>
      <td><code>STRING</code></td>
      <td>How the position was closed, as the venue labels its liquidation method. <code>liquidation</code> on MUX.</td>
    </tr>
  </tbody>
</table>

## Sample queries

<Warning>
  This table is large and split by day. Bound `block_timestamp` and filter `chain_id` on every query, or you read the whole table and the whole table is billed to you.
</Warning>

<Tabs>
  <Tab title="One market, one day">
    A position closed in pieces spans one row per fill, so `liquidated_user_address` repeats down the result for a single force-close.

    ```sql theme={null}
    select
        liquidations.block_timestamp,
        liquidations.trade_id,
        liquidations.liquidated_user_address,
        liquidations.side,
        liquidations.price,
        liquidations.trade_amount,
        liquidations.mark_price,
        liquidations.method
    from `facts_perp_markets.liquidations` as liquidations
    where liquidations.perp_market_id = 'hlbtc-hypercore'
      and liquidations.chain_id = 'hypercore'
      and liquidations.block_timestamp >= timestamp('2026-08-01')
      and liquidations.block_timestamp < timestamp('2026-08-02')
    order by liquidations.block_timestamp
    limit 100
    ```
  </Tab>

  <Tab title="Long vs short liquidations">
    `side` is the position that was closed, so summing `trade_amount * price` under each value separates the two. MUX execution prices are in USD, and the result matches the daily tables on [Metrics](/docs/catalog/perpetuals/metrics).

    ```sql theme={null}
    select
        date(liquidations.block_timestamp) as day,
        sum(if(liquidations.side = 'A', liquidations.trade_amount * liquidations.price, 0)) as long_liquidations,
        sum(if(liquidations.side = 'B', liquidations.trade_amount * liquidations.price, 0)) as short_liquidations
    from `facts_perp_markets.liquidations` as liquidations
    where liquidations.exchange_app_id = 'mux-perps'
      and liquidations.chain_id = 'arbitrum'
      and liquidations.block_timestamp >= timestamp('2026-08-01')
      and liquidations.block_timestamp < timestamp('2026-08-08')
    group by day
    order by day
    ```
  </Tab>

  <Tab title="Most liquidated accounts">
    `liquidated_user_address` is the account force-closed, and grouping on it adds every fill of every position it lost in the window.

    ```sql theme={null}
    select
        liquidations.liquidated_user_address,
        count(*) as fills,
        sum(liquidations.trade_amount * liquidations.price) as liquidated_notional
    from `facts_perp_markets.liquidations` as liquidations
    where liquidations.chain_id = 'hypercore'
      and liquidations.block_timestamp >= timestamp('2026-08-01')
      and liquidations.block_timestamp < timestamp('2026-08-08')
    group by liquidations.liquidated_user_address
    order by liquidated_notional desc
    limit 25
    ```
  </Tab>
</Tabs>