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

# Perpetuals Trades Feed

> Real-time perpetual futures trades from Hyperliquid (HyperCore) and Lighter over WebSocket: schema, parties, fees, liquidations, corrections and history in historical_perp_trades.

The Perpetuals Trades feed streams every perpetual futures fill on Hyperliquid (HyperCore), Lighter and Lighter Robinhood. Each WebSocket message holds one venue block. Each trade has the market, price, size, taker side, both parties with their fees and position change, and a USD value.

For connection, resume, corrections and latency, see the [Market Data Feeds overview](https://docs.dune.com/market-data-feeds/overview.md).

| Venue | `chain` | Endpoint |
| - | - | - |
| Hyperliquid (HyperCore) | `{"id": 1, "type": "hypercore"}` | `wss://api.dune.com/api/feed/perp/trades/1` |
| Lighter | `{"id": 1, "type": "lighter"}` | `wss://api.dune.com/api/feed/perp/trades/lighter/1` |
| Lighter Robinhood | `{"id": 2, "type": "lighter"}` | `wss://api.dune.com/api/feed/perp/trades/lighter/2` |

Instrument code examples: `ETH-USDC.HLPERP.HL` (Hyperliquid), `NVDA-USDC.XYZ.HLPERP.HL` (Hyperliquid HIP-3 sub-dex `xyz`), `BTC-USDC.LIGHTER` (Lighter), `ETH-USDG.LIGHTER.LRHC` (Lighter Robinhood).

Format: `perp-trades.json.v1`. History: `dune.dune.historical_perp_trades`, which also holds Kalshi perpetuals trades. Kalshi has no live public endpoint.

## Coverage

One day of history, 2026-11-17, from `historical_perp_trades`. Counts change from day to day.

| Venue | Markets with trades | Trades |
| - | - | - |
| Hyperliquid (HyperCore) | 351 | 5,895,273 |
| Lighter | 205 | 2,182,576 |
| Lighter Robinhood | 71 | 1,411,177 |
| Kalshi (history only) | 89 | 933,701 |

Hyperliquid includes HIP-3 builder markets; their sub-dex is in `venue.dex`. Lighter includes only linear perpetual markets with the deployment's quote asset (USDC on Lighter, USDG on Lighter Robinhood). Spot fills are not in the feed. To browse instruments, open the [instrument explorer](https://dune.com/data/feeds).

## Message envelope

| Field | Type | Description |
| - | - | - |
| `schema_version` | string | `perp-trades.json.v1` |
| `chain` | object | See the table above |
| `block_number` | integer | Venue block height |
| `block_timestamp` | string | Venue block time, RFC 3339, nanoseconds |
| `op` | string | `INSERT` or `UPDATE` |
| `incarnation_version` | integer | Increases with each correction. Keep the highest. |
| `trades` | array | The complete set of trades in the block. Can be empty. |
| `block_notification_time` | string | When Dune first saw the block. Omitted when unknown. |
| `sequence_number` | string | Resume cursor |

## Trade fields

Quantities and prices are exact decimal strings, for example `"1744.1"`. They have no exponent, and trailing zeros come from the venue. Compare them as numbers.

| Field | Type | Description |
| - | - | - |
| `trade_id` | string | Unique, stable trade identifier. Do not parse it. |
| `match_id` | string or null | The venue's own trade id |
| `tx.hash` | string or null | Venue transaction token. Format differs by venue. |
| `tx.index` | integer or null | Position in the block, when the venue has one |
| `tx.source_kind` | string | `match`, `event`, `log` or `trace` |
| `tx.source_index` | integer | Venue event ordinal. `0` on Lighter. |
| `venue.name` | string | `hyperliquid` or `lighter` |
| `venue.protocol` | string | `hypercore` or `lighter` |
| `venue.id` | string | `HLPERP.HL` or `LIGHTER` |
| `venue.market` | string | Display symbol, for example `BTC`. Not an identifier. |
| `venue.market_id` | string | Dune listing id. Within one venue, join on this field. |
| `venue.dex` | string | HIP-3 sub-dex, for example `xyz`. Omitted for the core dex. |
| `mechanism` | string | `order_book`, `pool` or `system` (backstop liquidation, auto-deleverage) |
| `kind` | string | `trade`, `liquidation`, `deleverage` or `settlement` |
| `base_symbol` | string or null | Base asset symbol |
| `quote` | object | `{symbol, venue_asset_id}`. The quote is also the settlement asset. |
| `side` | string or null | Taker side, `buy` or `sell`. `null` only for `settlement`. |
| `size` | string | Base quantity, greater than 0 |
| `executed_price` | string | Quote per base, greater than 0 |
| `executed_at` | string or null | Execution time, microseconds |
| `oracle_price` | string or null | Reserved. Not populated today. |
| `value_usd` | object or null | `{amount, source, stale}`. `source` is `pyth`, `chainlink` or `venue_reported`. `null` when unpriced. |
| `liquidation` | object | For `liquidation` and `deleverage` only: `liquidated_user`, `liquidated_account_id`, `mark_price`, `method` (`market` or `backstop`) |
| `condition_flags` | array | `unpriced`, `stale_usd_price`, `block_trade` |
| `instrument_code` | string | Dune instrument code. Use it to join across venues. Do not parse it. |
| `maker`, `taker` | object | See [Parties](#parties). `taker` is the aggressor. `maker` is `null` when the passive side is not on the venue's tape. |

### Parties

| Field | Description |
| - | - |
| `address` | Account address. Set on Hyperliquid. |
| `account_id` | Venue account number. Set on Lighter. |
| `position_side` | `long` or `short` before the fill. `null` when the position was flat. |
| `position_effect` | `open`, `increase`, `decrease`, `close` or `flip` |
| `position_before` | Signed position size before the fill, base units |
| `closed_pnl` | Realized PnL of this fill, quote units |
| `fee` | `{amount, asset, builder, protocol}`. `amount` is signed; a negative value is a rebate. |
| `order_id`, `client_order_id`, `twap_id` | Venue order identifiers |

### Venue notes

* **Hyperliquid:** `value_usd` is computed by Dune from an oracle price. A TWAP slice carries `twap_id` on one side. Backstop liquidations have `mechanism: system`; auto-deleverage rows have `kind: deleverage`.
* **Lighter:** parties are venue account numbers (`address` is `null`). `value_usd.source` is `venue_reported`: the USD amount Lighter reports. `tx.hash` is 80 hex characters without `0x`.

## Example

Hyperliquid, captured on 19 November 2026:

```json theme={null}
{
  "schema_version": "perp-trades.json.v1",
  "chain": { "id": 1, "type": "hypercore" },
  "block_number": 1227474590,
  "block_timestamp": "2026-11-19T21:37:16.635591361Z",
  "op": "INSERT",
  "incarnation_version": 0,
  "trades": [
    {
      "tx": {
        "hash": "0xc9d5de326e1ffca1cb4f044929c69e0208cb001809131b736d9e89852d13d68c",
        "index": null,
        "source_kind": "match",
        "source_index": 780184612480357
      },
      "trade_id": "hypercore-1-1227474590-1-match-780184612480357-0",
      "match_id": "780184612480357",
      "venue": { "name": "hyperliquid", "protocol": "hypercore", "id": "HLPERP.HL", "market": "ETH", "market_id": "1" },
      "mechanism": "order_book",
      "maker": {
        "address": "0x67f7aa8fb95c47e6ea9c517b623e0701cbf9d9ba",
        "account_id": null,
        "position_side": "long",
        "position_effect": "decrease",
        "position_before": "1.113",
        "closed_pnl": "0.38",
        "fee": { "amount": "-0.052323" },
        "order_id": "610683218718",
        "client_order_id": "0x0000000000000000000001a1eee4e844"
      },
      "taker": {
        "address": "0x8409149707ec6dbdb32c3dd0c2f0f02c1b505846",
        "account_id": null,
        "position_side": "long",
        "position_effect": "increase",
        "position_before": "6.0108",
        "closed_pnl": "0.0",
        "fee": { "amount": "0.69764" },
        "order_id": "610683219081"
      },
      "kind": "trade",
      "base_symbol": "ETH",
      "quote": { "symbol": "USDC", "venue_asset_id": "0" },
      "side": "buy",
      "size": "1.0",
      "executed_price": "1744.1",
      "executed_at": "2026-11-19T21:37:16.635591+00:00",
      "oracle_price": null,
      "value_usd": { "amount": "1743.85315753", "source": "chainlink", "stale": false },
      "condition_flags": [],
      "instrument_code": "ETH-USDC.HLPERP.HL"
    }
  ],
  "block_notification_time": "2026-11-19T21:37:16.970664763Z",
  "sequence_number": "153216197"
}
```

## Compatibility

Version 1 changes only by addition: new optional fields, new enum values, new venues. Any other change ships as `perp-trades.json.v2`. Keep unknown enum values instead of rejecting them.

## History

`dune.dune.historical_perp_trades` has one row per trade. Party fields are flattened with `taker_` and `maker_` prefixes, for example `taker_fee` and `maker_position_effect`.

| Venue | `chain_type`, `chain_id` | First day | Source |
| - | - | - | - |
| Lighter | `lighter`, `1` | 2025-01-17 | Lighter's daily public trade export |
| Hyperliquid | `hypercore`, `1` | 2025-07-27 | Hyperliquid node fill data, which starts on that day |
| Kalshi | `kalshi`, `1` | 2026-06-03 | Kalshi trade history |
| Lighter Robinhood | `lighter`, `2` | 2026-06-26 | Lighter's daily public trade export |

On 19 November 2026, every venue had a partition for every day from its first day to 2026-11-18. Known gaps, such as four Lighter blocks that Dune holds back because Lighter reports invalid rows in them, are listed in the data caveats below.

Kalshi notes: a block is one second of trades. Kalshi quotes per contract; Dune converts `size` and `executed_price` to base units. Kalshi's public tape has no parties and no liquidation marker.

```sql DuneSQL theme={null}
SELECT
  instrument_code,
  count(*) AS trades,
  sum(value_usd) AS volume_usd,
  count_if(kind = 'liquidation') AS liquidations
FROM dune.dune.historical_perp_trades
WHERE block_date = DATE '2026-11-17'
  AND chain_type = 'hypercore'
GROUP BY 1
ORDER BY volume_usd DESC
LIMIT 20
```

### Known data caveats

* Four Lighter blocks are missing from history: 61656974, 61657213 and 61657799 (2025-10-10) and 83816295 (2025-11-04).
* Lighter trades before 2025-12-22 have `executed_at` equal to the block time, because Lighter's export has no transaction time for them.
* From September to October 2026, eight Lighter markets were sent live under a second listing id (`<id>~1`) and code (for example `RAY2-USDC.LIGHTER`). History uses the original id and code.


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