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

# hip4_hyperliquid.market_trades

> Hyperliquid HIP-4 fill ledger — one row per fill leg, covering both sides of every trade plus the split, merge, negate and settlement legs.

export const TableSample = ({tableName, tableSchema}) => <>
    <div className="hidden dark:block">
      <iframe src={`https://dune.com/embeds/3419983/5785629?table_schema_t6f0df=${tableSchema}&table_name_t6f0df=${tableName}&darkMode=true`} style={{
  width: '100%',
  height: '500px',
  border: 'none',
  marginTop: '10px'
}} />
    </div>
    <div className="dark:hidden">
      <iframe src={`https://dune.com/embeds/3419983/5785629?table_schema_t6f0df=${tableSchema}&table_name_t6f0df=${tableName}`} style={{
  width: '100%',
  height: '500px',
  border: 'none',
  marginTop: '10px'
}} />
    </div>
  </>;

The `hip4_hyperliquid.market_trades` table is the Hyperliquid HIP-4 fill ledger. Grain: one row per fill leg, keyed on `(block_month, trade_id, trader, outcome_id)`. It has both sides of every match, plus the engine legs that mint, burn and settle outcome tokens. `fill_type` tells trades apart from the other legs. Every leg is present, so `start_position` gives each account's balance before every change, and positions and open interest can be rebuilt exactly.

A match is either:

* **Two legs on the same token**: a buyer and a seller, sharing a `trade_id`.
* **One leg on each side of the market**: a Yes buyer matched with a No buyer, or a Yes seller with a No seller, at prices that sum to 1. These legs have their own `trade_id`s and sit at consecutive `event_index` values in the same block.

<Warning>
  `SUM(amount_usd)` over all rows counts every match twice. For traded volume, filter `is_taker AND fill_type = 'trade'`.
</Warning>

## Table Schema

| Column | Type | Description |
| - | - | - |
| `block_month` | `DATE` | First day of the UTC month of `block_time`. Partition key |
| `block_date` | `DATE` | UTC date of the fill |
| `block_time` | `TIMESTAMP` | Block time of the fill |
| `block_number` | `BIGINT` | Block number |
| `event_index` | `INTEGER` | Position of the leg within the block. The two legs of a Yes-versus-No match sit at consecutive indices |
| `tx_hash` | `VARBINARY` | Hash of the action that produced the fill |
| `trade_id` | `BIGINT` | Fill identifier (Hyperliquid `tid`). Shared by both legs on the same token. Unique across taker legs |
| `order_id` | `BIGINT` | Order this leg filled (Hyperliquid `oid`). Engine legs carry an engine-minted id |
| `client_order_id` | `VARCHAR` | Client order id (Hyperliquid `cloid`), where the trader set one |
| `twap_id` | `BIGINT` | TWAP order this leg is a child slice of. Set only on the taker leg |
| `market_id` | `VARCHAR` | Market identifier. Joins `hip4_hyperliquid.market_details` |
| `outcome_id` | `VARCHAR` | Outcome token traded on this leg, in Hyperliquid's coin notation `#N` |
| `outcome_index` | `INTEGER` | Side of the market: `0` is Yes, `1` is No |
| `trader` | `VARBINARY` | Account on this leg |
| `is_system_account` | `BOOLEAN` | TRUE when the account is the venue's settlement counterparty. Exclude from supply, open interest and position measures |
| `is_taker` | `BOOLEAN` | TRUE on the aggressor leg. Filter it to count each match once |
| `side` | `VARCHAR` | `buy` or `sell` from this leg's perspective. Buying No is not the same as selling Yes: see `outcome_index` |
| `dir` | `VARCHAR` | Venue-native fill direction, passed through. Prefer `fill_type` |
| `fill_type` | `VARCHAR` | `trade` (order matched on the book — the only type that reflects price discovery), `split` (collateral minted into a Yes/No pair), `merge` (Yes/No pair burned back to collateral), `negate` (a No token converted into Yes tokens of the question's other outcomes), `merge_question` (one Yes of every outcome burned back to collateral), `settlement` (holder redeemed at the payout), `other` |
| `start_position` | `DOUBLE` | Tokens of `outcome_id` the account held before this leg |
| `price` | `DOUBLE` | Price of `outcome_id` in the quote stablecoin, 0 to 1. Not always the Yes price: on a No leg, Yes price is `1 - price`. Splits and merges are booked at 0.5 per side; settlement legs carry the payout |
| `num_contracts` | `DOUBLE` | Outcome tokens on this leg |
| `amount_usd` | `DOUBLE` | `price * num_contracts` in the market's quote stablecoin |
| `closed_pnl_usd` | `DOUBLE` | Realised PnL on this leg, non-zero when tokens are sold, merged or settled |
| `fee_usd` | `DOUBLE` | Total fee in the quote stablecoin, builder and deployer fees included. Fees are charged on the side receiving the quote asset |
| `builder_fee_usd` | `DOUBLE` | Builder (front-end) share of `fee_usd`. NULL on legs not routed through a builder |
| `deployer_fee_usd` | `DOUBLE` | Market deployer's share of `fee_usd`. NULL where no deployer fee applies |
| `fee_token` | `VARCHAR` | Token the fee is denominated in |
| `builder` | `VARBINARY` | Builder (front-end) address, on legs routed through a builder |
| `_updated_at` | `TIMESTAMP` | When this row was last written by the pipeline |

## Table sample

<TableSample tableSchema="hip4_hyperliquid" tableName="market_trades" />

## Query performance

`block_month` is the partition key. Always include a `block_month` filter alongside any `block_time` range.

## Example query

For volume and trade counts only, [`open_interest_hourly`](/data-catalog/curated/prediction-markets/hip4/open_interest_hourly) is much cheaper and returns the same totals. Use `market_trades` when you need what only the ledger has: individual accounts, fees, and non-trade legs. Fees are charged on merge and settlement legs as well as trades, so fee totals should include every fill type.

```sql theme={null}
-- Daily fee revenue by recipient and active traders, last 30 days
SELECT
  block_date,
  SUM(fee_usd - COALESCE(builder_fee_usd, 0) - COALESCE(deployer_fee_usd, 0)) AS protocol_fee_usd,
  SUM(builder_fee_usd) AS builder_fee_usd,
  SUM(deployer_fee_usd) AS deployer_fee_usd,
  COUNT(DISTINCT trader) AS active_traders
FROM hip4_hyperliquid.market_trades
WHERE block_month >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '30' DAY)
  AND block_time >= NOW() - INTERVAL '30' DAY
  AND NOT is_system_account
GROUP BY 1
ORDER BY 1
```


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