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

# Trades

> Individual perpetual and order-book trades.

One row per leg of a perpetual fill, and one row per order-book fill. `trade_amount` is the size traded on a perpetual leg, and `trade_amount_raw` the same size as a decimal string on an order-book fill.

## Columns

**Perpetual**

`facts_perp_markets.trades` holds one row per leg, keyed by `block_timestamp`, `perp_market_id`, `trade_id`, `trader_address` and `crossed`. HyperCore fills have maker and taker legs; MUX pool executions have one trader leg.

<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 trade. Partition column.</td>
    </tr>

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

    <tr>
      <td>`trade_id`</td>
      <td>`INT64`</td>
      <td>Fill identifier shared by both HyperCore legs; fingerprint of chain, transaction hash and log index on MUX. Part of the row key with `block_timestamp`, `perp_market_id`, `trader_address` and `crossed`.</td>
    </tr>

    <tr>
      <td>`perp_market_id`</td>
      <td>`STRING`</td>
      <td>Market the trade executed 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. Every fill in a market has the same value.</td>
    </tr>

    <tr>
      <td>`exchange_app_id`</td>
      <td>`STRING`</td>
      <td>The venue that executed the trade. The same fill 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 trade executed on.</td>
    </tr>

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

    <tr>
      <td>`trader_address`</td>
      <td>`STRING`</td>
      <td>Address of the trader on this leg. Part of the row key.</td>
    </tr>

    <tr>
      <td>`side`</td>
      <td>`STRING`</td>
      <td>Which side this leg is: `B` for the buyer, `A` for the seller.</td>
    </tr>

    <tr>
      <td>`crossed`</td>
      <td>`BOOL`</td>
      <td>True on a HyperCore taker leg or a MUX pool execution; 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>`fee`</td>
      <td>`BIGNUMERIC`</td>
      <td>Fee charged on this leg, in `fee_token`, before sharing. Null on MUX executions, where fees can involve several tokens.</td>
    </tr>

    <tr>
      <td>`fee_token`</td>
      <td>`STRING`</td>
      <td>Token the fee was charged in. Null on MUX executions.</td>
    </tr>

    <tr>
      <td>`builder_fee`</td>
      <td>`BIGNUMERIC`</td>
      <td>The front end's share inside that fee. Null on MUX executions.</td>
    </tr>

    <tr>
      <td>`deployer_fee`</td>
      <td>`BIGNUMERIC`</td>
      <td>The market deployer's share inside that fee. Null on MUX executions.</td>
    </tr>

    <tr>
      <td>`trade_amount`</td>
      <td>`BIGNUMERIC`</td>
      <td>Size traded on this leg, in units of the underlying asset. Times `price` it is the leg's notional in the HyperCore settlement token or in USD on MUX.</td>
    </tr>
  </tbody>
</table>

**Order book**

`facts_order_book_markets.trades` holds one row per fill, with the maker and the taker on the same row as `maker_*` and `taker_*` columns. Amounts are decimal strings, following the datashare's convention for fact amounts, and `safe_cast(price_raw as bignumeric)` puts one back into arithmetic.

<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 fill. Partition column.</td>
    </tr>

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

    <tr>
      <td>`unique_id`</td>
      <td>`INT64`</td>
      <td>Row key: fingerprint of `order_book_market_id`, `trade_id` and `block_timestamp`.</td>
    </tr>

    <tr>
      <td>`trade_id`</td>
      <td>`INT64`</td>
      <td>Identifier of the fill within its market and block.</td>
    </tr>

    <tr>
      <td>`order_book_market_id`</td>
      <td>`STRING`</td>
      <td>Market the trade executed in, keyed like [`dimensions.order_book_markets`](https://tokenterminal.com/docs/catalog/perpetuals/registry).</td>
    </tr>

    <tr>
      <td>`app_id`</td>
      <td>`STRING`</td>
      <td>The app running the book, read from the registry.</td>
    </tr>

    <tr>
      <td>`token_id`</td>
      <td>`STRING`</td>
      <td>The market's quote token, keyed like [`dimensions.tokens`](https://tokenterminal.com/docs/catalog/tokens/registry).</td>
    </tr>

    <tr>
      <td>`chain_id`</td>
      <td>`STRING`</td>
      <td>Chain the trade executed on.</td>
    </tr>

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

    <tr>
      <td>`maker_address`</td>
      <td>`STRING`</td>
      <td>Address of the maker, whose order was resting on the book. Null on a single-leg match.</td>
    </tr>

    <tr>
      <td>`taker_address`</td>
      <td>`STRING`</td>
      <td>Address of the taker, who accepted the resting order. Null on a single-leg match.</td>
    </tr>

    <tr>
      <td>`maker_side`</td>
      <td>`STRING`</td>
      <td>Which way the maker traded: `B` for a buy, `A` for a sell. Null on a single-leg match with a maker side missing.</td>
    </tr>

    <tr>
      <td>`taker_side`</td>
      <td>`STRING`</td>
      <td>Which way the taker traded: `B` for a buy, `A` for a sell. Null on a single-leg match with a taker side missing.</td>
    </tr>

    <tr>
      <td>`match_leg_count`</td>
      <td>`INT64`</td>
      <td>How many legs the match wrote: two on an ordinary fill, one on a HIP-4 outcome-market mint or burn, which settles against the venue itself.</td>
    </tr>

    <tr>
      <td>`price_raw`</td>
      <td>`STRING`</td>
      <td>Price the trade filled at, in the quote token, as a decimal string.</td>
    </tr>

    <tr>
      <td>`trade_amount_raw`</td>
      <td>`STRING`</td>
      <td>How much was traded, in the base token, as a decimal string. Times `price_raw` it is the fill's value, which [Metrics](https://tokenterminal.com/docs/catalog/perpetuals/metrics.md) turns into dollars on the market-and-token tables.</td>
    </tr>

    <tr>
      <td>`maker_fee_raw`</td>
      <td>`STRING`</td>
      <td>Fee charged on the maker's side, in `maker_fee_token`, as a decimal string.</td>
    </tr>

    <tr>
      <td>`taker_fee_raw`</td>
      <td>`STRING`</td>
      <td>Fee charged on the taker's side, in `taker_fee_token`, as a decimal string.</td>
    </tr>

    <tr>
      <td>`maker_fee_token`</td>
      <td>`STRING`</td>
      <td>Token the maker's fee was charged in.</td>
    </tr>

    <tr>
      <td>`taker_fee_token`</td>
      <td>`STRING`</td>
      <td>Token the taker's fee was charged in. The taker is charged in the token received, so this is either side of the pair.</td>
    </tr>

    <tr>
      <td>`maker_builder_fee_raw`</td>
      <td>`STRING`</td>
      <td>The front end's share inside the maker's fee, as a decimal string.</td>
    </tr>

    <tr>
      <td>`taker_builder_fee_raw`</td>
      <td>`STRING`</td>
      <td>The front end's share inside the taker's fee, as a decimal string.</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**

`trade_amount` is the size in whatever the market tracks and `price` the settlement-token price it filled at; multiply them for the leg's notional value.

```sql theme={null}
select
    trades.block_timestamp,
    trades.trade_id,
    trades.trader_address,
    trades.side,
    trades.crossed,
    trades.price,
    trades.trade_amount,
    trades.fee
from `facts_perp_markets.trades` as trades
where trades.perp_market_id = 'hlbtc-hypercore'
  and trades.chain_id = 'hypercore'
  and trades.block_timestamp >= timestamp('2026-08-01')
  and trades.block_timestamp < timestamp('2026-08-02')
order by trades.block_timestamp
limit 100
```

**Pool volume by market**

MUX executions have one trader leg with `crossed = true`, and `price * trade_amount` is the executed notional in USD. The registry supplies the market name through `perp_market_id`.

```sql theme={null}
select
    trades.perp_market_id,
    markets.name,
    sum(trades.price * trades.trade_amount) as notional_volume_usd
from `facts_perp_markets.trades` as trades
join `dimensions.perp_markets` as markets
    using (perp_market_id)
where trades.exchange_app_id = 'mux-perps'
  and trades.chain_id = 'arbitrum'
  and trades.crossed
  and trades.block_timestamp >= timestamp('2026-08-01')
  and trades.block_timestamp < timestamp('2026-08-02')
group by trades.perp_market_id, markets.name
order by notional_volume_usd desc
```

**One order book, one day**

`price_raw` and `trade_amount_raw` are decimal strings, and `safe_cast` to `bignumeric` puts them back into arithmetic.

```sql theme={null}
select
    trades.block_timestamp,
    trades.trade_id,
    trades.maker_address,
    trades.taker_address,
    trades.taker_side,
    safe_cast(trades.price_raw as bignumeric) as price,
    safe_cast(trades.trade_amount_raw as bignumeric) as trade_amount
from `facts_order_book_markets.trades` as trades
where trades.order_book_market_id = '@107-hypercore'
  and trades.chain_id = 'hypercore'
  and trades.block_timestamp >= timestamp('2026-08-01')
  and trades.block_timestamp < timestamp('2026-08-02')
order by trades.block_timestamp
limit 100
```

**Order book volume**

One row is one fill, and the product of price and size is counted once per trade. `match_leg_count` reads 1 on a mint or burn, where the match has a single leg.

```sql theme={null}
select
    date(trades.block_timestamp) as day,
    sum(safe_cast(trades.price_raw as bignumeric)
        * safe_cast(trades.trade_amount_raw as bignumeric)) as trading_volume
from `facts_order_book_markets.trades` as trades
where trades.order_book_market_id = '@107-hypercore'
  and trades.chain_id = 'hypercore'
  and trades.block_timestamp >= timestamp('2026-08-01')
  and trades.block_timestamp < timestamp('2026-08-08')
group by day
order by day
```


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