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

# Trades

> Hyperliquid HIP-4 prediction-market trades.

The `hyperliquid.predictions.trades` table contains every Hyperliquid HIP-4 prediction-market trade. `event_name = 'Settlement'` rows mark settlement events; all other rows are regular trades.

## Table Columns

### Identifiers

| Column Name       | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| event\_name       | Event type: 'Trade' for a fill, 'Settlement' for a settlement event. |
| project           | Top-level project namespace (`hyperliquid`).                         |
| protocol          | Protocol within the project (`hyperliquid_hip4`).                    |
| chain             | The blockchain network (`hyperliquid`).                              |
| exchange\_type    | Trade execution venue type (`orderbook`).                            |
| coin              | HL-native side-token identifier (e.g. '#54760').                     |
| encoding          | HL-canonical numeric encoding for the side-token.                    |
| outcome\_id       | HIP-4 outcome identifier (shared by both token sides).               |
| token\_side       | Which side of the outcome's YES/NO pair the row represents (0 or 1). |
| asset\_id         | HL-canonical numeric identifier for the side-token.                  |
| trade\_id         | The HL trade ID (`tid`).                                             |
| transaction\_hash | The HL transaction hash for the fill.                                |
| timestamp         | UTC timestamp of the fill.                                           |
| unique\_id        | Deterministic unique identifier per row.                             |
| \_created\_at     | Row creation timestamp.                                              |
| \_updated\_at     | Row last update timestamp.                                           |

### Counterparties

| Column Name       | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| buyer\_address    | Buyer of the side-token.                                             |
| seller\_address   | Seller of the side-token.                                            |
| maker\_address    | Maker (resting-order) address. NULL on synthetic mints.              |
| taker\_address    | Taker (aggressing-order) address.                                    |
| side\_name        | One of 'BUY', 'SELL', 'SETTLE'. NULL on some synthetic-mint rows.    |
| buyer\_dir        | Direction string for the buyer leg (e.g. 'Open Long', 'Settlement'). |
| seller\_dir       | Direction string for the seller leg.                                 |
| buyer\_crossed    | Whether the buyer's order was the aggressor.                         |
| seller\_crossed   | Whether the seller's order was the aggressor.                        |
| buyer\_order\_id  | Order ID for the buyer's order.                                      |
| seller\_order\_id | Order ID for the seller's order.                                     |
| buyer\_twap\_id   | TWAP order ID if the buyer's order was a TWAP order.                 |
| seller\_twap\_id  | TWAP order ID if the seller's order was a TWAP order.                |

### Trade Economics

| Column Name                 | Description                                          |
| --------------------------- | ---------------------------------------------------- |
| price                       | Trade price as a 0..1 probability.                   |
| size                        | Trade size in side-tokens.                           |
| collateral\_token           | Collateral token symbol for the trade (e.g. 'USDH'). |
| collateral\_token\_decimals | Decimals of the collateral token.                    |
| collateral\_amount          | Native-unit collateral value of the trade.           |
| usd\_exchange\_rate         | USD price of the collateral token. 1.0 for USDH.     |
| usd\_collateral\_amount     | USD value of the trade.                              |

### Fees

| Column Name               | Description                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| fee\_token                | Token in which the trade fee was paid (e.g. 'USDH', 'USDC'). NULL when no fee was charged.    |
| seller\_fee\_token        | Token in which the seller's fee was paid. HIP-4 buyer and seller can pay in different tokens. |
| buyer\_fee\_token         | Token in which the buyer's fee was paid.                                                      |
| buyer\_fee                | Buyer-side fee in `buyer_fee_token` units.                                                    |
| seller\_fee               | Seller-side fee in `seller_fee_token` units.                                                  |
| buyer\_fee\_usd           | Buyer-side fee in USD.                                                                        |
| seller\_fee\_usd          | Seller-side fee in USD.                                                                       |
| tx\_fee                   | Total fee for the transaction in native token units.                                          |
| tx\_fee\_usd              | Total fee for the transaction in USD.                                                         |
| builder\_fee              | Total builder fee for the trade.                                                              |
| buyer\_builder\_fee       | Builder fee paid by the buyer, in `buyer_fee_token` units.                                    |
| seller\_builder\_fee      | Builder fee paid by the seller, in `seller_fee_token` units.                                  |
| buyer\_builder\_fee\_usd  | Buyer's builder fee in USD.                                                                   |
| seller\_builder\_fee\_usd | Seller's builder fee in USD.                                                                  |
| buyer\_builder\_address   | Builder address that received the buyer's builder fee.                                        |
| seller\_builder\_address  | Builder address that received the seller's builder fee.                                       |

### Position & PnL

| Column Name             | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| buyer\_start\_position  | Buyer's position in this side-token before the trade.                         |
| seller\_start\_position | Seller's position in this side-token before the trade.                        |
| buyer\_closed\_pnl      | Closed PnL realized by the buyer on this fill.                                |
| seller\_closed\_pnl     | Closed PnL realized by the seller on this fill.                               |
| is\_synthetic\_mint     | True when the trade represents a synthetic mint, burn, or cross-coin pairing. |

## Sample Query

```sql theme={null}
SELECT
  timestamp,
  coin,
  side_name,
  size,
  price,
  usd_collateral_amount,
  buyer_address,
  seller_address
FROM hyperliquid.predictions.trades
WHERE timestamp >= CURRENT_DATE - 7
  AND event_name = 'Trade'
ORDER BY timestamp DESC
LIMIT 100
```