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

# ez_perp_liquidations

> hypercore.core.ez_perp_liquidations

**Schema**: `hypercore.core` **Table**: `ez_perp_liquidations` **Type**: View

## What

Perpetual market liquidation events from the liquidated user's perspective, with counterparty
information. Comparable to Tornado and lending protocol liquidation tables.

## Sample queries

```sql theme={null}
-- Liquidation heatmap: when do liquidations spike? (last 14 days)
SELECT
    block_timestamp::DATE AS dt,
    HOUR(block_timestamp) AS hour_utc,
    coin,
    COUNT(*) AS liquidations,
    ROUND(SUM(trade_notional), 0) AS liquidated_usd,
    COUNT(DISTINCT liquidated_address) AS unique_users_liquidated
FROM hypercore.core.ez_perp_liquidations
WHERE block_timestamp >= DATEADD('day', -14, CURRENT_DATE)
    AND coin IN ('BTC', 'ETH')
GROUP BY 1, 2, 3
ORDER BY 1, 2;
```

```sql theme={null}
-- Largest single liquidations (last 30 days)
SELECT
    block_timestamp,
    coin,
    liquidated_address,
    counterparty_address,
    liquidation_method,
    price,
    trade_size,
    ROUND(trade_notional, 2) AS notional_usd,
    liquidated_direction,
    ROUND(liquidated_closed_pnl, 2) AS realized_loss
FROM hypercore.core.ez_perp_liquidations
WHERE block_timestamp >= DATEADD('day', -30, CURRENT_DATE)
ORDER BY trade_notional DESC
LIMIT 25;
```

## Columns

| Column Name                 | Data Type      | Description                                                                                                                        |
| --------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| TRADE\_ID                   | NUMBER         | Unique trade identifier assigned by the Hyperliquid L1 matching engine.                                                            |
| BLOCK\_NUMBER               | NUMBER         | L1 block number containing this event.                                                                                             |
| BLOCK\_TIMESTAMP            | TIMESTAMP\_NTZ | Block production timestamp on the Hyperliquid L1. This is the canonical time for ordering blockchain events.                       |
| COIN                        | TEXT           | Raw asset identifier. Perps use plain ticker (e.g. BTC), spot uses @token\_index format (e.g. @2), prelaunch uses xyz:name prefix. |
| SYMBOL                      | TEXT           | Human-readable trading symbol. Resolved from token metadata for spot tokens; same as coin for perps.                               |
| TRADE\_TIMESTAMP            | TIMESTAMP\_NTZ | Exact fill timestamp from the matching engine, may differ slightly from block\_timestamp.                                          |
| TX\_HASH                    | TEXT           | L1 transaction hash uniquely identifying the on-chain transaction.                                                                 |
| PRICE                       | FLOAT          | Execution price in USD for this trade.                                                                                             |
| TRADE\_SIZE                 | FLOAT          | Size of the trade in base asset units.                                                                                             |
| TRADE\_NOTIONAL             | FLOAT          | USD notional value of the trade (price x size), rounded to 2 decimal places.                                                       |
| LIQUIDATED\_USER            | TEXT           | Address of the user being liquidated. NULL if this is not a liquidation trade.                                                     |
| LIQUIDATION\_MARK\_PRICE    | FLOAT          | Mark price at the time of liquidation. NULL if not a liquidation.                                                                  |
| LIQUIDATION\_METHOD         | TEXT           | Method used for the liquidation (e.g. backstop, market). NULL if not a liquidation.                                                |
| LIQUIDATED\_ADDRESS         | TEXT           | Address of the liquidated user on this trade.                                                                                      |
| COUNTERPARTY\_ADDRESS       | TEXT           | Address of the counterparty (liquidator or backstop vault).                                                                        |
| LIQUIDATED\_DIRECTION       | TEXT           | Trade direction of the liquidated user's position.                                                                                 |
| LIQUIDATED\_FEE             | FLOAT          | Fee charged to the liquidated user.                                                                                                |
| LIQUIDATED\_CLOSED\_PNL     | FLOAT          | Realized PnL for the liquidated user.                                                                                              |
| LIQUIDATED\_START\_POSITION | FLOAT          | Liquidated user's position size before the liquidation fill.                                                                       |
| FEE\_TOKEN                  | TEXT           | Token in which trading fees are denominated.                                                                                       |
| MARKET\_TYPE                | TEXT           | Type of market: 'perp' for perpetual futures, 'spot' for HIP-1 token trading, 'prelaunch' for pre-listing futures.                 |
| MODIFIED\_TIMESTAMP         | TIMESTAMP\_NTZ | Timestamp when the record was last modified in this table (Snowflake SYSDATE).                                                     |
| FACT\_TRADES\_ID            | TEXT           | Surrogate key for fact\_trades, generated as MD5 hash of trade\_id.                                                                |
| EZ\_PERP\_LIQUIDATIONS\_ID  | TEXT           | Surrogate key for this liquidation record, generated from fact\_trades\_id and liquidated\_user.                                   |
| \_INVOCATION\_ID            | TEXT           | dbt invocation identifier for tracking which run produced this record.                                                             |