> ## 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>`block_timestamp`</td>
      <td>`TIMESTAMP`</td>
      <td>Time of the block containing the liquidation fill. Partition column.</td>
    </tr>

    <tr>
      <td>`block_number`</td>
      <td>`INT64`</td>
      <td>Number of the block containing the liquidation fill.</td>
    </tr>

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

    <tr>
      <td>`trade_id`</td>
      <td>`INT64`</td>
      <td>Forced-fill identifier on HyperCore; fingerprint of chain, transaction hash and log index on MUX. Part of the row key with `block_timestamp`, `perp_market_id`, `liquidated_user_address` and `crossed`.</td>
    </tr>

    <tr>
      <td>`perp_market_id`</td>
      <td>`STRING`</td>
      <td>Market the position was liquidated in, keyed like [`dimensions.perp_markets`](https://tokenterminal.com/docs/catalog/perpetuals/registry).</td>
    </tr>

    <tr>
      <td>`interface_app_id`</td>
      <td>`STRING`</td>
      <td>The builder credited for the market, read from the registry.</td>
    </tr>

    <tr>
      <td>`exchange_app_id`</td>
      <td>`STRING`</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>`token_id`</td>
      <td>`STRING`</td>
      <td>The market's settlement token, keyed like [`dimensions.tokens`](https://tokenterminal.com/docs/catalog/tokens/registry). Null on MUX markets, which accept several collateral tokens.</td>
    </tr>

    <tr>
      <td>`chain_id`</td>
      <td>`STRING`</td>
      <td>Chain the liquidation happened on.</td>
    </tr>

    <tr>
      <td>`project_id`</td>
      <td>`STRING`</td>
      <td>Project the exchange app belongs to.</td>
    </tr>

    <tr>
      <td>`liquidated_user_address`</td>
      <td>`STRING`</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>`side`</td>
      <td>`STRING`</td>
      <td>The position that was force-closed: `A` for a long, `B` for a short.</td>
    </tr>

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

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

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

    <tr>
      <td>`mark_price`</td>
      <td>`BIGNUMERIC`</td>
      <td>Mark price the liquidation was triggered at. Null on MUX executions.</td>
    </tr>

    <tr>
      <td>`method`</td>
      <td>`STRING`</td>
      <td>How the position was closed, as the venue labels its liquidation method. `liquidation` 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.

**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
```

**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](https://tokenterminal.com/docs/catalog/perpetuals/metrics.md).

```sql theme={null}
select
    date(liquidations.block_timestamp) as day,
    sum(if(liquidations.side = 'A', liquidations.trade_amount * liquidations.price, 0)) as liquidation_volume_long,
    sum(if(liquidations.side = 'B', liquidations.trade_amount * liquidations.price, 0)) as liquidation_volume_short
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
```

**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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.