Types

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

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.

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

Outcome

Market outcome. Used in OrderArgs and orderbook filtering.

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.

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.

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)

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.

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.

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.

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:

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

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