# Types

All data types are Python dataclasses defined in `turbine_client.types`. They are returned by `TurbineClient` methods and can be imported directly.

```python
from turbine_client import Side, Outcome, OrderArgs, SignedOrder
from turbine_client.types import (
    Market, MarketStats, OrderBookSnapshot, PriceLevel, Trade, Position,
    QuickMarket, Resolution, Order, AssetPrice, UserActivity, UserStats,
    PermitSignature, Holder, PlatformStats, ChainStats,
    FailedTrade, PendingTrade, FailedClaim, PendingClaim, SettlementStatus,
    WSMessage, OrderBookUpdate, TradeUpdate, QuickMarketUpdate,
)
```

## Enums

### Side

Order side. Used in `OrderArgs` and order filtering.

```python
class Side(IntEnum):
    BUY = 0
    SELL = 1
```

### Outcome

Market outcome. Used in `OrderArgs` and orderbook filtering.

```python
class Outcome(IntEnum):
    YES = 0
    NO = 1
```

## Order Types

### OrderArgs

Arguments for creating a new order. Passed to `client.create_order()`.

| Field                 | Type      | Description                                          |
| --------------------- | --------- | ---------------------------------------------------- |
| `market_id`           | `str`     | Market ID (hex string)                               |
| `side`                | `Side`    | `Side.BUY` or `Side.SELL`                            |
| `outcome`             | `Outcome` | `Outcome.YES` or `Outcome.NO`                        |
| `price`               | `int`     | Price scaled by 1e6 (`1`–`999999`; `500000` = $0.50) |
| `size`                | `int`     | Size with 6 decimals (`1000000` = 1 share)           |
| `expiration`          | `int`     | Unix timestamp for order expiry                      |
| `nonce`               | `int`     | Auto-generated if `0` (default)                      |
| `maker_fee_recipient` | `str`     | Fee recipient address (default: zero address)        |

Validation runs on construction. Raises `ValueError` if price is outside `1`–`999999` or size is not positive.

```python
import time
from turbine_client import OrderArgs, Side, Outcome

args = OrderArgs(
    market_id="0xabc123...",
    side=Side.BUY,
    outcome=Outcome.YES,
    price=450000,                    # $0.45
    size=10000000,                   # 10 shares
    expiration=int(time.time()) + 3600,
)
```

### SignedOrder

A signed order ready for submission via `client.post_order()`.

| Field                 | Type                      | Description                   |
| --------------------- | ------------------------- | ----------------------------- |
| `market_id`           | `str`                     | Market ID                     |
| `trader`              | `str`                     | Signer's wallet address       |
| `side`                | `int`                     | `0` (buy) or `1` (sell)       |
| `outcome`             | `int`                     | `0` (YES) or `1` (NO)         |
| `price`               | `int`                     | Price (6 decimals)            |
| `size`                | `int`                     | Size (6 decimals)             |
| `nonce`               | `int`                     | Order nonce                   |
| `expiration`          | `int`                     | Expiration timestamp          |
| `maker_fee_recipient` | `str`                     | Fee recipient address         |
| `signature`           | `str`                     | EIP-712 signature (hex)       |
| `order_hash`          | `str`                     | Computed order hash (hex)     |
| `permit_signature`    | `PermitSignature \| None` | Optional attached USDC permit |

Created by `client.create_order()`, `client.create_limit_buy()`, or `client.create_limit_sell()`. Call `signed.to_dict()` for the API-ready JSON payload.

```python
signed = client.create_limit_buy(
    market_id="0x...",
    outcome=Outcome.YES,
    price=500000,
    size=1000000,
)

# Optionally attach a permit
permit = client.sign_usdc_permit(value=500000)
signed.permit_signature = permit

# Submit
result = client.post_order(signed)
```

### PermitSignature

EIP-2612 permit signature for gasless USDC approval. Returned by `client.sign_usdc_permit()`.

| Field      | Type  | Description                                |
| ---------- | ----- | ------------------------------------------ |
| `nonce`    | `int` | Permit nonce (must match on-chain)         |
| `value`    | `int` | Approved amount (6 decimals)               |
| `deadline` | `int` | Expiration timestamp                       |
| `v`        | `int` | Signature `v` component                    |
| `r`        | `str` | Signature `r` component (hex, 0x-prefixed) |
| `s`        | `str` | Signature `s` component (hex, 0x-prefixed) |

```python
permit = client.sign_usdc_permit(value=10000000)  # $10
print(f"Permit nonce: {permit.nonce}, deadline: {permit.deadline}")
```

### Order

An order on the orderbook. Returned by `client.get_orders()`, `client.get_order()`, `client.get_user_orders()`.

| Field            | Type  | Description                            |
| ---------------- | ----- | -------------------------------------- |
| `order_hash`     | `str` | Order hash                             |
| `market_id`      | `str` | Market ID                              |
| `trader`         | `str` | Trader address                         |
| `side`           | `int` | `0` = buy, `1` = sell                  |
| `outcome`        | `int` | `0` = YES, `1` = NO                    |
| `price`          | `int` | Price (6 decimals)                     |
| `size`           | `int` | Original size (6 decimals)             |
| `filled_size`    | `int` | Amount filled (6 decimals)             |
| `remaining_size` | `int` | Amount remaining (6 decimals)          |
| `nonce`          | `int` | Order nonce                            |
| `expiration`     | `int` | Expiration timestamp                   |
| `status`         | `str` | `"open"`, `"filled"`, or `"cancelled"` |
| `created_at`     | `int` | Creation timestamp                     |

## Market Types

### Market

A prediction market. Returned by `client.get_markets()`.

| Field                | Type          | Description                                 |
| -------------------- | ------------- | ------------------------------------------- |
| `id`                 | `str`         | Market ID (hex, used for API calls)         |
| `chain_id`           | `int`         | Chain ID                                    |
| `contract_address`   | `str`         | Market contract address (used for claiming) |
| `settlement_address` | `str`         | Settlement contract address                 |
| `question`           | `str`         | Market question text                        |
| `description`        | `str`         | Market description                          |
| `category`           | `str`         | Market category                             |
| `expiration`         | `int`         | Expiration timestamp                        |
| `maker`              | `str`         | Market creator address                      |
| `resolved`           | `bool`        | Whether the market is resolved              |
| `winning_outcome`    | `int \| None` | `0` (YES) or `1` (NO) if resolved           |
| `volume`             | `int`         | Total volume (6 decimals)                   |
| `created_at`         | `int`         | Creation timestamp                          |
| `updated_at`         | `int`         | Last update timestamp                       |

### MarketStats

Statistics for a market. Returned by `client.get_market()`, `client.get_stats()`.

| Field              | Type  | Description                                     |
| ------------------ | ----- | ----------------------------------------------- |
| `market_id`        | `str` | Market ID                                       |
| `contract_address` | `str` | Market contract address                         |
| `last_price`       | `int` | Last trade price (6 decimals; `500000` = $0.50) |
| `total_volume`     | `int` | Total volume (6 decimals)                       |
| `volume_24h`       | `int` | 24-hour volume (6 decimals)                     |

### QuickMarket

A 15-minute quick market. Returned by `client.get_quick_market()`, `client.get_quick_market_history()`.

| Field              | Type          | Description                                            |
| ------------------ | ------------- | ------------------------------------------------------ |
| `id`               | `int`         | Auto-increment ID                                      |
| `market_id`        | `str`         | Market ID (hex)                                        |
| `asset`            | `str`         | Asset symbol (`"BTC"`, `"ETH"`)                        |
| `interval_minutes` | `int`         | Duration in minutes (`15`)                             |
| `start_price`      | `int`         | Strike price (8 decimals; divide by `1e8` for dollars) |
| `end_price`        | `int \| None` | Final price at resolution                              |
| `start_time`       | `int`         | Start timestamp                                        |
| `end_time`         | `int`         | Expiration timestamp                                   |
| `resolved`         | `bool`        | Whether resolved                                       |
| `outcome`          | `int \| None` | `0` (YES) or `1` (NO) if resolved                      |
| `price_source`     | `str`         | Oracle source (e.g., `"pyth"`)                         |
| `created_at`       | `int`         | Creation timestamp                                     |
| `contract_address` | `str`         | Market contract address                                |

### Resolution

Market resolution status. Returned by `client.get_resolution()`.

| Field          | Type   | Description                           |
| -------------- | ------ | ------------------------------------- |
| `market_id`    | `str`  | Market ID                             |
| `assertion_id` | `str`  | UMA assertion ID                      |
| `outcome`      | `int`  | Winning outcome (`0` = YES, `1` = NO) |
| `resolved`     | `bool` | Whether resolved                      |
| `timestamp`    | `int`  | Resolution timestamp                  |

## Orderbook Types

### OrderBookSnapshot

Orderbook state for a market. Returned by `client.get_orderbook()`.

| Field         | Type               | Description                    |
| ------------- | ------------------ | ------------------------------ |
| `market_id`   | `str`              | Market ID                      |
| `bids`        | `list[PriceLevel]` | Bid levels (sorted best-first) |
| `asks`        | `list[PriceLevel]` | Ask levels (sorted best-first) |
| `last_update` | `int`              | Last update timestamp          |

### PriceLevel

A single price level in the orderbook.

| Field   | Type  | Description                                                |
| ------- | ----- | ---------------------------------------------------------- |
| `price` | `int` | Price (6 decimals; `500000` = $0.50)                       |
| `size`  | `int` | Total size at this level (6 decimals; `1000000` = 1 share) |

## Trade Types

### Trade

A trade execution. Returned by `client.get_trades()`.

| Field       | Type  | Description                  |
| ----------- | ----- | ---------------------------- |
| `id`        | `int` | Trade ID                     |
| `market_id` | `str` | Market ID                    |
| `buyer`     | `str` | Buyer address                |
| `seller`    | `str` | Seller address               |
| `price`     | `int` | Execution price (6 decimals) |
| `size`      | `int` | Execution size (6 decimals)  |
| `outcome`   | `int` | `0` = YES, `1` = NO          |
| `timestamp` | `int` | Execution timestamp          |
| `tx_hash`   | `str` | Settlement transaction hash  |

## Position Types

### Position

A user's position in a market. Returned by `client.get_positions()`, `client.get_user_positions()`.

| Field            | Type  | Description                               |
| ---------------- | ----- | ----------------------------------------- |
| `id`             | `int` | Position ID                               |
| `market_id`      | `str` | Market ID                                 |
| `user_address`   | `str` | User address                              |
| `yes_shares`     | `int` | YES token balance (6 decimals)            |
| `no_shares`      | `int` | NO token balance (6 decimals)             |
| `yes_cost`       | `int` | USDC spent on YES (6 decimals)            |
| `no_cost`        | `int` | USDC spent on NO (6 decimals)             |
| `yes_revenue`    | `int` | USDC received from YES sales (6 decimals) |
| `no_revenue`     | `int` | USDC received from NO sales (6 decimals)  |
| `total_invested` | `int` | Total USDC invested (6 decimals)          |
| `total_cost`     | `int` | Total USDC cost (6 decimals)              |
| `total_revenue`  | `int` | Total USDC revenue (6 decimals)           |
| `last_updated`   | `int` | Last sync timestamp                       |

### Holder

A top holder in a market. Returned by `client.get_holders()`.

| Field            | Type  | Description                      |
| ---------------- | ----- | -------------------------------- |
| `user_address`   | `str` | Holder address                   |
| `yes_shares`     | `int` | YES token balance (6 decimals)   |
| `no_shares`      | `int` | NO token balance (6 decimals)    |
| `total_invested` | `int` | Total USDC invested (6 decimals) |

## User Types

### UserActivity

Trading activity summary. Returned by `client.get_user_activity()`.

| Field            | Type  | Description               |
| ---------------- | ----- | ------------------------- |
| `address`        | `str` | User address              |
| `total_trades`   | `int` | Total number of trades    |
| `total_volume`   | `int` | Total volume (6 decimals) |
| `pnl`            | `int` | Profit/Loss (6 decimals)  |
| `markets_traded` | `int` | Number of markets traded  |

### UserStats

User portfolio statistics. Returned by `client.get_user_stats()`.

| Field            | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `user_address`   | `str`   | User address                        |
| `total_cost`     | `int`   | Total USDC spent (6 decimals)       |
| `total_invested` | `int`   | Total USDC invested (6 decimals)    |
| `position_value` | `int`   | Current position value (6 decimals) |
| `pnl`            | `int`   | Profit/Loss (6 decimals)            |
| `pnl_percentage` | `float` | PNL as a percentage                 |

## Platform Types

### PlatformStats

Platform-wide statistics. Returned by `client.get_platform_stats()`.

| Field          | Type               | Description                                 |
| -------------- | ------------------ | ------------------------------------------- |
| `chains`       | `list[ChainStats]` | Per-chain statistics                        |
| `total_volume` | `int`              | Total volume across all chains (6 decimals) |
| `total_trades` | `int`              | Total trades across all chains              |

### ChainStats

Per-chain statistics.

| Field          | Type  | Description               |
| -------------- | ----- | ------------------------- |
| `chain_id`     | `int` | Chain ID                  |
| `total_volume` | `int` | Total volume (6 decimals) |
| `total_trades` | `int` | Total trades              |
| `updated_at`   | `int` | Last update timestamp     |

### AssetPrice

Current price for an asset. Returned by `client.get_quick_market_price()`.

| Field       | Type    | Description                                           |
| ----------- | ------- | ----------------------------------------------------- |
| `price`     | `float` | Price in smallest units (divide by `1e8` for dollars) |
| `timestamp` | `int`   | Price timestamp                                       |

## Settlement Tracking Types

### FailedTrade

A failed trade settlement.

| Field            | Type  | Description             |
| ---------------- | ----- | ----------------------- |
| `market_id`      | `str` | Market ID               |
| `tx_hash`        | `str` | Transaction hash        |
| `buyer_address`  | `str` | Buyer address           |
| `seller_address` | `str` | Seller address          |
| `fill_size`      | `int` | Fill size (6 decimals)  |
| `fill_price`     | `int` | Fill price (6 decimals) |
| `reason`         | `str` | Failure reason          |
| `timestamp`      | `str` | Failure timestamp       |
| `batch_index`    | `int` | Batch index             |

### PendingTrade

A pending trade settlement.

| Field            | Type   | Description             |
| ---------------- | ------ | ----------------------- |
| `market_id`      | `str`  | Market ID               |
| `tx_hash`        | `str`  | Transaction hash        |
| `buyer_address`  | `str`  | Buyer address           |
| `seller_address` | `str`  | Seller address          |
| `fill_size`      | `int`  | Fill size (6 decimals)  |
| `fill_price`     | `int`  | Fill price (6 decimals) |
| `timestamp`      | `str`  | Submission timestamp    |
| `is_batch`       | `bool` | Whether part of a batch |
| `batch_index`    | `int`  | Batch index             |

### FailedClaim

A failed redemption claim.

| Field             | Type  | Description                  |
| ----------------- | ----- | ---------------------------- |
| `tx_hash`         | `str` | Transaction hash             |
| `user_address`    | `str` | User address                 |
| `market_address`  | `str` | Market contract address      |
| `market_id`       | `str` | Market ID                    |
| `payout`          | `int` | Expected payout (6 decimals) |
| `winning_outcome` | `int` | Winning outcome              |
| `submitted_at`    | `int` | Submission timestamp         |

### PendingClaim

A pending redemption claim. Same fields as `FailedClaim`.

### SettlementStatus

Settlement status for a transaction.

| Field            | Type   | Description                         |
| ---------------- | ------ | ----------------------------------- |
| `found`          | `bool` | Whether the transaction was found   |
| `tx_hash`        | `str`  | Transaction hash                    |
| `status`         | `str`  | Settlement status                   |
| `error`          | `str`  | Error message (empty if successful) |
| `market_id`      | `str`  | Market ID                           |
| `buyer_address`  | `str`  | Buyer address                       |
| `seller_address` | `str`  | Seller address                      |
| `fill_size`      | `int`  | Fill size (6 decimals)              |
| `fill_price`     | `int`  | Fill price (6 decimals)             |
| `timestamp`      | `str`  | Timestamp                           |
| `is_batch`       | `bool` | Whether part of a batch             |
| `batch_index`    | `int`  | Batch index                         |

## WebSocket Message Types

### WSMessage

Base WebSocket message. All other message types inherit from this.

| Field       | Type          | Description                                                                    |
| ----------- | ------------- | ------------------------------------------------------------------------------ |
| `type`      | `str`         | Message type (`"orderbook"`, `"trade"`, `"quick_market"`, `"order_cancelled"`) |
| `market_id` | `str \| None` | Associated market ID                                                           |
| `data`      | `Any`         | Raw message data                                                               |

### OrderBookUpdate

Extends `WSMessage`. Has an `orderbook` property.

```python
if msg.type == "orderbook":
    ob = msg.orderbook  # Returns OrderBookSnapshot or None
    if ob:
        print(f"Bids: {len(ob.bids)}, Asks: {len(ob.asks)}")
```

### TradeUpdate

Extends `WSMessage`. Has a `trade` property.

```python
if msg.type == "trade":
    trade = msg.trade  # Returns Trade or None
    if trade:
        print(f"Trade: {trade.size / 1e6:.2f} @ {trade.price} (${trade.price / 1e6:.4f})")
```

### QuickMarketUpdate

Extends `WSMessage`. Has a `quick_market` property.

```python
if msg.type == "quick_market":
    qm = msg.quick_market  # Returns QuickMarket or None
    if qm:
        print(f"New market: {qm.market_id}")
```

## Helper Functions

Available from `turbine_client.order_builder.helpers`:

```python
from turbine_client.order_builder.helpers import (
    price_to_decimal,    # 500000 → Decimal('0.5')
    decimal_to_price,    # 0.5 → 500000
    size_to_shares,      # 1000000 → Decimal('1')
    shares_to_size,      # 1.5 → 1500000
    calculate_cost,      # cost = price * size / 1e6
    calculate_payout,    # payout = size (winners get 1:1)
    calculate_profit,    # profit = payout - cost
    validate_price,      # raises OrderValidationError
    validate_size,       # raises OrderValidationError
    round_price_down,    # round to tick size
    round_price_up,      # round to tick size
    round_size_down,     # round to minimum increment
)
```

### Examples

```python
from turbine_client.order_builder.helpers import (
    calculate_cost, calculate_profit, price_to_decimal, decimal_to_price
)

# Cost of buying 10 shares at $0.45
cost = calculate_cost(450000, 10000000)  # 4500000 = $4.50 USDC

# Profit if the bet wins
profit = calculate_profit(450000, 10000000)  # 5500000 = $5.50 USDC

# Price conversions
price_to_decimal(750000)   # Decimal('0.75')
decimal_to_price(0.33)     # 330000
```