Skip to main content

OrderBookSnapshot

A snapshot of the order book for a market.
market_id
str
Market identifier
bids
list[PriceLevel]
List of buy orders (sorted by price descending)
asks
list[PriceLevel]
List of sell orders (sorted by price ascending)
last_update
int
Unix timestamp of last orderbook update

Methods

from_dict(data)

Creates an OrderBookSnapshot instance from an API response dictionary.

Example

orderbook = client.get_orderbook(market_id="0xabc...")

print(f"Market: {orderbook.market_id}")
print(f"Last Update: {orderbook.last_update}")
print("\nBids (Buy Orders):")
for level in orderbook.bids[:5]:  # Top 5
    print(f"  Price: {level.price / 1e6:.2%}, Size: {level.size / 1e6:.2f}")

print("\nAsks (Sell Orders):")
for level in orderbook.asks[:5]:  # Top 5
    print(f"  Price: {level.price / 1e6:.2%}, Size: {level.size / 1e6:.2f}")

# Calculate spread
if orderbook.bids and orderbook.asks:
    best_bid = orderbook.bids[0].price / 1e6
    best_ask = orderbook.asks[0].price / 1e6
    spread = (best_ask - best_bid) * 100
    print(f"\nSpread: {spread:.2f}%")

PriceLevel

A single price level in the orderbook.
price
int
Price scaled by 1e6 (divide by 1,000,000 to get percentage)
size
int
Total size available at this price (6 decimals)

Methods

from_dict(data)

Creates a PriceLevel instance from an API response dictionary.

Example

level = PriceLevel(price=650_000, size=10_000_000)

print(f"Price: {level.price / 1e6:.2%}")  # 65.00%
print(f"Size: {level.size / 1e6:.2f} shares")  # 10.00 shares

Trade

A trade execution.
id
int
Unique trade ID
market_id
str
Market identifier
buyer
str
Buyer’s wallet address
seller
str
Seller’s wallet address
price
int
Execution price (scaled by 1e6)
size
int
Trade size (6 decimals)
outcome
int
Outcome traded (0 = YES, 1 = NO)
timestamp
int
Trade execution timestamp
tx_hash
str
Transaction hash

Methods

from_dict(data)

Creates a Trade instance from an API response dictionary.

Example

trades = client.get_trades(market_id="0xabc...", limit=10)

for trade in trades:
    outcome = "YES" if trade.outcome == 0 else "NO"
    print(f"Trade {trade.id}:")
    print(f"  {outcome} @ {trade.price / 1e6:.2%}")
    print(f"  Size: {trade.size / 1e6:.2f} shares")
    print(f"  Value: ${(trade.price * trade.size) / 1e12:.2f}")
    print(f"  Tx: {trade.tx_hash[:10]}...")

Position

A user’s position in a market.
id
int
Position ID
market_id
str
Market identifier
user_address
str
User’s wallet address
yes_shares
int
Number of YES shares held (6 decimals)
no_shares
int
Number of NO shares held (6 decimals)
yes_cost
int
Total cost of YES shares (in USDC with 6 decimals)
no_cost
int
Total cost of NO shares (in USDC with 6 decimals)
yes_revenue
int
Revenue from selling YES shares (in USDC with 6 decimals)
no_revenue
int
Revenue from selling NO shares (in USDC with 6 decimals)
total_invested
int
Total USDC invested in this position (6 decimals)
total_cost
int
Net cost after accounting for revenue (6 decimals)
total_revenue
int
Total revenue from this position (6 decimals)
last_updated
int
Last update timestamp

Methods

from_dict(data)

Creates a Position instance from an API response dictionary.

Example

positions = client.get_user_positions(user_address="0xabc...")

for pos in positions:
    print(f"Market: {pos.market_id[:10]}...")
    print(f"  YES: {pos.yes_shares / 1e6:.2f} shares (cost: ${pos.yes_cost / 1e6:.2f})")
    print(f"  NO: {pos.no_shares / 1e6:.2f} shares (cost: ${pos.no_cost / 1e6:.2f})")
    print(f"  Net Cost: ${pos.total_cost / 1e6:.2f}")
    print(f"  Revenue: ${pos.total_revenue / 1e6:.2f}")

Holder

A top holder in a market.
user_address
str
User’s wallet address
yes_shares
int
Number of YES shares held (6 decimals)
no_shares
int
Number of NO shares held (6 decimals)
total_invested
int
Total USDC invested (6 decimals)

Methods

from_dict(data)

Creates a Holder instance from an API response dictionary.

ClaimablePosition

A resolved market where the user has winning tokens to claim.
market_id
str
Market identifier
contract_address
str
Market contract address
outcome_label
str
Winning outcome label (“YES” or “NO”)
balance
int
Raw token balance (6 decimals)
payout
str
Human-readable payout (e.g., “10.50”)

Properties

payout_float

Returns the payout as a float (balance / 1,000,000).

Methods

from_dict(data)

Creates a ClaimablePosition instance from an API response dictionary.

Example

claimable = client.get_claim_data(user_address="0xabc...")

for claim in claimable:
    print(f"Market: {claim.market_id[:10]}...")
    print(f"  Outcome: {claim.outcome_label}")
    print(f"  Payout: ${claim.payout_float:.2f}")
    print(f"  Contract: {claim.contract_address}")

# Claim all at once
if claimable:
    contracts = [c.contract_address for c in claimable]
    result = client.batch_claim_winnings(contracts)
    print(f"Claimed from {len(contracts)} markets")

UserActivity

User trading activity summary.
address
str
User’s wallet address
total_trades
int
Total number of trades
total_volume
int
Total trading volume (in USDC with 6 decimals)
pnl
int
Profit and loss (in USDC with 6 decimals)
markets_traded
int
Number of unique markets traded

Methods

from_dict(data)

Creates a UserActivity instance from an API response dictionary.

UserStats

Detailed user statistics.
user_address
str
User’s wallet address
total_cost
int
Total USDC spent on positions (6 decimals)
total_invested
int
Total USDC invested in positions (6 decimals)
position_value
int
Current value of all positions (6 decimals)
pnl
int
Profit/Loss (6 decimals)
pnl_percentage
float
PnL as percentage

Methods

from_dict(data)

Creates a UserStats instance from an API response dictionary.

Example

stats = client.get_user_stats(user_address="0xabc...")

print(f"Total Invested: ${stats.total_invested / 1e6:,.2f}")
print(f"Position Value: ${stats.position_value / 1e6:,.2f}")
print(f"PnL: ${stats.pnl / 1e6:,.2f} ({stats.pnl_percentage:.2f}%)")

PendingTrade

A trade that is pending on-chain confirmation.
market_id
str
Market identifier
tx_hash
str
Transaction hash
buyer_address
str
Buyer’s wallet address
seller_address
str
Seller’s wallet address
fill_size
int
Trade size (6 decimals)
fill_price
int
Execution price (scaled by 1e6)
timestamp
str
Submission timestamp
is_batch
bool
Whether this is part of a batch
batch_index
int
Index within the batch (if applicable)

Methods

from_dict(data)

Creates a PendingTrade instance from an API response dictionary.

FailedTrade

A trade that failed on-chain.
market_id
str
Market identifier
tx_hash
str
Transaction hash
buyer_address
str
Buyer’s wallet address
seller_address
str
Seller’s wallet address
fill_size
int
Attempted trade size (6 decimals)
fill_price
int
Attempted execution price (scaled by 1e6)
reason
str
Reason for failure
timestamp
str
Submission timestamp
batch_index
int
Index within the batch (if applicable)

Methods

from_dict(data)

Creates a FailedTrade instance from an API response dictionary.

SettlementStatus

Settlement status for a transaction.
found
bool
Whether the transaction was found
tx_hash
str
Transaction hash
status
str
Status (e.g., “pending”, “confirmed”, “failed”)
error
str
Error message if failed
market_id
str
Market identifier
buyer_address
str
Buyer’s wallet address
seller_address
str
Seller’s wallet address
fill_size
int
Trade size (6 decimals)
fill_price
int
Execution price (scaled by 1e6)
timestamp
str
Timestamp
is_batch
bool
Whether this is part of a batch
batch_index
int
Index within the batch (if applicable)

Methods

from_dict(data)

Creates a SettlementStatus instance from an API response dictionary.

AssetPrice

Current price data for an asset.
asset
string
Asset symbol (e.g., “BTC”, “ETH”)
price
int
Current price scaled by 1e6 (e.g., 97250000000 = $97,250.00)
timestamp
int
Unix timestamp when price was fetched

Methods

from_dict(data)
classmethod
Creates an AssetPrice instance from an API response dictionary.

Example

from turbine_client import TurbineClient

client = TurbineClient(host="https://api.turbinefi.com", chain_id=137)

# Get current BTC price
price = client.get_quick_market_price(asset="BTC")
print(f"BTC: ${price.price / 1e6:,.2f}")
print(f"Updated: {price.timestamp}")

FailedClaim

A claim transaction that failed.
tx_hash
string
Transaction hash of the failed claim
user_address
string
User’s wallet address
market_address
string
Market contract address
market_id
string
Market identifier
payout
int
Expected payout amount (6 decimals)
winning_outcome
int
Winning outcome (0=YES, 1=NO)
submitted_at
int
Unix timestamp when claim was submitted

Methods

from_dict(data)
classmethod
Creates a FailedClaim instance from an API response dictionary.

Example

# Get failed claims
failed = client.get_failed_claims()
for claim in failed:
    print(f"Failed claim: {claim.tx_hash}")
    print(f"  Market: {claim.market_id}")
    print(f"  Payout: ${claim.payout / 1e6:.2f}")

PendingClaim

A claim transaction pending confirmation.
tx_hash
string
Transaction hash of the pending claim
user_address
string
User’s wallet address
market_address
string
Market contract address
market_id
string
Market identifier
payout
int
Expected payout amount (6 decimals)
winning_outcome
int
Winning outcome (0=YES, 1=NO)
submitted_at
int
Unix timestamp when claim was submitted

Methods

from_dict(data)
classmethod
Creates a PendingClaim instance from an API response dictionary.

Example

# Get pending claims
pending = client.get_pending_claims()
for claim in pending:
    print(f"Pending claim: {claim.tx_hash}")
    print(f"  Market: {claim.market_id}")
    print(f"  Payout: ${claim.payout / 1e6:.2f}")

Build docs developers (and LLMs) love