Trades

A fill is one trade matched between two traders. Each of its two sides gets its own row, and a side is called a leg. Each row carries both the leg’s size and the fees charged on it, so fees, volume or both read from one table.

facts.perp_trades: one row per leg of a perpetual fill.
facts.order_book_trades: one row per leg of a spot or outcome-market fill.

trade_id is shared by both legs of one fill. Within a fill, (trader_address, crossed) picks out a leg. crossed is true on the taker’s leg: the trader who accepted an order that was already there. It is false on the maker’s leg: the trader whose order was sitting waiting. That pair also handles a self-trade, where one address is on both sides and the two legs differ only on crossed.

Tables

Perp trades
Order book trades

facts.perp_trades holds one row per leg of a perpetual fill, keyed by block_timestamp, perp_market_id, trade_id, trader_address and crossed.

Column	Type	Description
`block_timestamp`	`TIMESTAMP`	Time of the block this trade landed in.
`block_number`	`INT64`	Number of that block.
`trade_id`	`INT64`	Identifier shared by both legs of the same fill. Part of the row key, alongside `perp_market_id`, `trader_address` and `crossed`.
`perp_market_id`	`STRING`	Market the trade executed in, keyed like `dimensions.perp_markets`.
`interface_app_id`	`STRING`	The app whose front end the trade came through, read from the registry table.
`exchange_app_id`	`STRING`	The venue that matched the trade.
`token_id`	`STRING`	The market’s settlement token.
`chain_id`	`STRING`	Chain the trade executed on.
`project_id`	`STRING`	Project the exchange app belongs to.
`trader_address`	`STRING`	Address of the trader on this side.
`side`	`STRING`	Which side this leg is: `B` for the buyer, `A` for the seller.
`crossed`	`BOOL`	True on the taker’s leg, the trader who accepted an order that was already there; false on the maker’s.
`price`	`BIGNUMERIC`	Price the trade filled at, in the settlement token.
`fee`	`BIGNUMERIC`	Fee charged on this leg, in `fee_token`, before anything is shared out.
`fee_token`	`STRING`	Token the fee was charged in.
`builder_fee`	`BIGNUMERIC`	The front end’s share inside that fee.
`deployer_fee`	`BIGNUMERIC`	The share going to whoever listed the market, inside that fee.
`trade_amount`	`BIGNUMERIC`	How much was traded, in whatever the market tracks.

facts.order_book_trades holds one row per leg of a spot or outcome-market fill, keyed by block_timestamp, order_book_market_id, trade_id, trader_address and crossed. block_timestamp has to be part of the key because events that are not trades all carry trade_id = 0.

Column	Type	Description
`block_timestamp`	`TIMESTAMP`	Time of the block this trade landed in. Part of the row key.
`block_number`	`INT64`	Number of that block.
`trade_id`	`INT64`	Identifier shared by both legs of the same fill. Zero on events that are not trades. Part of the row key, alongside `order_book_market_id`, `trader_address` and `crossed`.
`order_book_market_id`	`STRING`	Market the trade executed in, keyed like `dimensions.order_book_markets`.
`app_id`	`STRING`	The app running the book, read from the registry table. Empty when that table does not carry the market.
`token_id`	`STRING`	The market’s quote token.
`chain_id`	`STRING`	Chain the trade executed on.
`project_id`	`STRING`	Project the operating app belongs to.
`trader_address`	`STRING`	Address of the trader on this side.
`side`	`STRING`	Which side this leg is: `B` for the buyer, `A` for the seller.
`crossed`	`BOOL`	True on the taker’s leg, the trader who accepted an order that was already there; false on the maker’s.
`match_leg_count`	`INT64`	How many legs the match wrote: two on an ordinary fill, one on a mint or burn.
`price`	`BIGNUMERIC`	Price the trade filled at, in the quote token.
`fee`	`BIGNUMERIC`	Fee charged on this leg, in `fee_token`, before anything is shared out.
`fee_token`	`STRING`	Token the fee was charged in. On these books the taker is charged in the token they received, so the fee can land on either side of the pair.
`builder_fee`	`BIGNUMERIC`	The front end’s share inside that fee.
`trade_amount`	`BIGNUMERIC`	How much was traded, in the base token.

Sample queries

Put a filter on block_timestamp in every query. Both tables are partitioned on it, and leaving the filter out reads the whole history.

One market, one day
Order-book volume

Read one perpetual market’s trades on a single day. trade_amount is how much was traded, measured in whatever the market tracks, and price is the price it filled at. Multiply them for the trade’s notional value: the value of the contracts traded, which is not the same as cash changing hands.

select
    block_timestamp,
    trade_id,
    trader_address,
    side,
    crossed,
    price,
    trade_amount,
    fee
from `facts.perp_trades`
where perp_market_id = 'hlbtc-hypercore'
  and block_timestamp >= timestamp('2026-08-01')
  and block_timestamp < timestamp('2026-08-02')
order by block_timestamp
limit 100

Total one order-book market’s volume over a window. Both legs of an ordinary fill describe the same trade, so venue volume counts only the taker’s leg. A match that wrote a single leg, a mint or a burn, is counted in full. That is what the (crossed or match_leg_count = 1) filter does.

select
    timestamp_trunc(block_timestamp, day) as day,
    sum(price * trade_amount) as trading_volume
from `facts.order_book_trades`
where order_book_market_id = '@107-hypercore'
  and (crossed or match_leg_count = 1)
  and block_timestamp >= timestamp('2026-08-01')
  and block_timestamp < timestamp('2026-08-08')
group by day
order by day

Notes

A fee is charged on each side separately, so a fee total adds up every row. Volume is different. Both legs of an ordinary fill describe one trade at one value, so counting both doubles the venue’s volume. Count one leg per fill. Both tables carry token amounts and no dollar column. Amounts become dollars once, on the market-and-token daily tables described on Metrics, which is what makes every broader total agree with the ones beneath it.

Overview

Core entities

Market verticals

Chain verticals

Tables

Sample queries

Notes

​Tables

​Sample queries

​Notes

Tables

Sample queries

Notes