> For the complete documentation index, see [llms.txt](https://docs.ojolabs.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ojolabs.xyz/markets/api/python-sdk/types.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ojolabs.xyz/markets/api/python-sdk/types.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.