Overview
All market data endpoints are public - no authentication required. You can query markets, orderbooks, and trades without API credentials.from turbine_client import TurbineClient
# Public client (no auth needed)
client = TurbineClient(
host="https://api.turbinefi.com",
chain_id=137, # Polygon mainnet
)
Markets
Get All Markets
Retrieve a list of all markets across all chains:markets = client.get_markets()
for market in markets:
print(f"Question: {market.question}")
print(f" ID: {market.id}")
print(f" Chain: {market.chain_id}")
print(f" Category: {market.category}")
print(f" Resolved: {market.resolved}")
print(f" Volume: ${market.volume / 1e6:,.2f}")
print()
Filter by Chain
# Get markets on Polygon only
polygon_markets = client.get_markets(chain_id=137)
# Get markets on Avalanche
avalanche_markets = client.get_markets(chain_id=43114)
Get Quick Markets (BTC/ETH/SOL)
Quick markets are 15-minute prediction markets for crypto assets:# Get the current active BTC quick market
btc_market = client.get_quick_market("BTC")
print(f"Question: {btc_market.question}")
print(f"Strike Price: ${btc_market.start_price / 1e6:,.2f}")
print(f"Market ID: {btc_market.market_id}")
print(f"Expires: {btc_market.end_time}")
print(f"Resolved: {btc_market.resolved}")
# Also available for ETH and SOL
eth_market = client.get_quick_market("ETH")
sol_market = client.get_quick_market("SOL")
Get Quick Market History
Retrieve past quick markets for an asset:# Get historical BTC quick markets
history = client.get_quick_market_history("BTC", limit=10)
for market in history:
print(f"Strike: ${market.start_price / 1e6:,.2f}")
print(f" Resolved: {market.resolved}")
if market.resolved:
outcome = "YES" if market.winning_outcome == 0 else "NO"
print(f" Winner: {outcome}")
print()
Get Single Market Details
Fetch detailed information about a specific market:market = client.get_market(market_id="0x1234...")
print(f"Question: {market.question}")
print(f"Description: {market.description}")
print(f"Category: {market.category}")
print(f"Contract: {market.contract_address}")
print(f"Settlement: {market.settlement_address}")
print(f"Maker: {market.maker}")
print(f"Expiration: {market.expiration}")
print(f"Created: {market.created_at}")
Orderbooks
Get Full Orderbook
Retrieve the current orderbook snapshot for a market:orderbook = client.get_orderbook(market_id="0x1234...")
print(f"Last updated: {orderbook.last_update}")
print(f"Bids: {len(orderbook.bids)}")
print(f"Asks: {len(orderbook.asks)}")
# Display top 5 bids
print("\nTop Bids (buyers):")
for bid in orderbook.bids[:5]:
price_pct = bid.price / 10000 # Convert to percentage
shares = bid.size / 1_000_000
print(f" {price_pct:.2f}% - {shares:.2f} shares")
# Display top 5 asks
print("\nTop Asks (sellers):")
for ask in orderbook.asks[:5]:
price_pct = ask.price / 10000
shares = ask.size / 1_000_000
print(f" {price_pct:.2f}% - {shares:.2f} shares")
Filter by Outcome
Get orderbook for a specific outcome (YES or NO):from turbine_client import Outcome
# Get YES orderbook only
yes_book = client.get_orderbook(market_id="0x1234...", outcome=Outcome.YES)
# Get NO orderbook only
no_book = client.get_orderbook(market_id="0x1234...", outcome=Outcome.NO)
Calculate Spread
orderbook = client.get_orderbook(market_id)
if orderbook.bids and orderbook.asks:
best_bid = orderbook.bids[0].price / 10000
best_ask = orderbook.asks[0].price / 10000
spread = best_ask - best_bid
spread_bps = spread * 100 # Basis points
print(f"Best Bid: {best_bid:.2f}%")
print(f"Best Ask: {best_ask:.2f}%")
print(f"Spread: {spread:.2f}% ({spread_bps:.0f} bps)")
print(f"Mid Price: {(best_bid + best_ask) / 2:.2f}%")
Calculate Orderbook Depth
def calculate_depth(levels: list, up_to_price: int) -> float:
"""Calculate total size up to a given price level."""
total_size = 0
for level in levels:
if level.price <= up_to_price:
total_size += level.size
else:
break
return total_size / 1_000_000 # Convert to shares
orderbook = client.get_orderbook(market_id)
# Calculate bid depth up to 48%
bid_depth = calculate_depth(orderbook.bids, 480000)
print(f"Bid depth to 48%: {bid_depth:.2f} shares")
# Calculate ask depth up to 52%
ask_depth = calculate_depth(orderbook.asks, 520000)
print(f"Ask depth to 52%: {ask_depth:.2f} shares")
Trades
Get Recent Trades
Retrieve trade history for a market:# Get last 100 trades (default)
trades = client.get_trades(market_id="0x1234...")
for trade in trades[:10]: # Show first 10
price_pct = trade.price / 10000
shares = trade.size / 1_000_000
outcome = "YES" if trade.outcome == 0 else "NO"
timestamp = time.strftime('%H:%M:%S', time.localtime(trade.timestamp))
print(f"{timestamp} - {shares:.2f} {outcome} @ {price_pct:.2f}%")
print(f" Buyer: {trade.buyer[:10]}...")
print(f" Seller: {trade.seller[:10]}...")
print(f" Tx: {trade.tx_hash[:10]}...")
Get Trades with Limit
# Get last 50 trades
recent_trades = client.get_trades(market_id="0x1234...", limit=50)
# Get last 200 trades
all_trades = client.get_trades(market_id="0x1234...", limit=200)
Calculate Volume
import time
def calculate_volume_24h(trades: list) -> float:
"""Calculate 24-hour trading volume in USDC."""
cutoff = time.time() - 86400 # 24 hours ago
volume = 0
for trade in trades:
if trade.timestamp >= cutoff:
# Volume = size × price / 1e12
volume += (trade.size * trade.price) / 1e12
return volume
trades = client.get_trades(market_id)
volume_24h = calculate_volume_24h(trades)
print(f"24h Volume: ${volume_24h:,.2f} USDC")
Analyze Trade Direction
def analyze_trade_pressure(trades: list, last_n: int = 20) -> dict:
"""Analyze recent trade direction."""
recent = trades[:last_n]
yes_volume = 0
no_volume = 0
for trade in recent:
volume = (trade.size * trade.price) / 1e12
if trade.outcome == 0: # YES
yes_volume += volume
else: # NO
no_volume += volume
total = yes_volume + no_volume
return {
"yes_volume": yes_volume,
"no_volume": no_volume,
"yes_pct": (yes_volume / total * 100) if total > 0 else 0,
"no_pct": (no_volume / total * 100) if total > 0 else 0,
}
trades = client.get_trades(market_id)
pressure = analyze_trade_pressure(trades)
print(f"Recent trade pressure (last 20 trades):")
print(f" YES: {pressure['yes_pct']:.1f}%")
print(f" NO: {pressure['no_pct']:.1f}%")
Statistics
Get Market Statistics
stats = client.get_stats(market_id="0x1234...")
print(f"Market Statistics:")
print(f" Volume 24h: ${stats.volume_24h / 1e6:,.2f}")
print(f" Last Price: {stats.last_price / 10000:.2f}%")
print(f" Price Change 24h: {stats.price_change_24h:.2f}%")
print(f" High 24h: {stats.high_24h / 10000:.2f}%")
print(f" Low 24h: {stats.low_24h / 10000:.2f}%")
print(f" Num Trades: {stats.num_trades}")
Get Platform Statistics
platform_stats = client.get_platform_stats()
print(f"Platform Statistics:")
print(f" Total Markets: {platform_stats.market_count}")
print(f" Total Volume: ${platform_stats.total_volume / 1e6:,.2f}")
print(f" Active Traders: {platform_stats.active_traders}")
print(f" Markets Resolved: {platform_stats.resolved_count}")
Asset Prices (Quick Markets)
Get Current Price
Fetch the real-time price for BTC, ETH, or SOL:# Get current BTC price
btc_price = client.get_quick_market_price("BTC")
print(f"BTC: ${btc_price.price:,.2f}")
print(f"Last updated: {btc_price.timestamp}")
# Get current ETH price
eth_price = client.get_quick_market_price("ETH")
print(f"ETH: ${eth_price.price:,.2f}")
Get Price History
Retrieve historical price data:# Get BTC price history
price_history = client.get_quick_market_price_history("BTC", limit=100)
for price_point in price_history[:10]:
timestamp = time.strftime('%H:%M:%S', time.localtime(price_point.timestamp))
print(f"{timestamp}: ${price_point.price:,.2f}")
Resolution Status
Check if Market is Resolved
resolution = client.get_resolution(market_id="0x1234...")
if resolution.resolved:
outcome = "YES" if resolution.outcome == 0 else "NO"
print(f"Market resolved: {outcome} won")
print(f"Assertion ID: {resolution.assertion_id}")
print(f"Timestamp: {resolution.timestamp}")
else:
print("Market not yet resolved")
Position & Holder Data
Get Top Holders
See who holds the most shares in a market:holders = client.get_holders(market_id="0x1234...")
print("Top Holders:")
for holder in holders[:10]:
print(f" {holder.address[:10]}...")
print(f" YES shares: {holder.yes_shares / 1e6:.2f}")
print(f" NO shares: {holder.no_shares / 1e6:.2f}")
Complete Example: Market Monitor
Here’s a complete script that monitors a market:market_monitor.py
import time
from turbine_client import TurbineClient
client = TurbineClient(
host="https://api.turbinefi.com",
chain_id=137,
)
def monitor_market(market_id: str):
"""Monitor a market and display key metrics."""
while True:
try:
# Get market details
market = client.get_market(market_id)
# Get orderbook
orderbook = client.get_orderbook(market_id)
# Get recent trades
trades = client.get_trades(market_id, limit=10)
# Get stats
stats = client.get_stats(market_id)
# Clear screen and display
print("\033[2J\033[H") # Clear terminal
print(f"Market: {market.question}")
print(f"Time: {time.strftime('%H:%M:%S')}\n")
# Orderbook
if orderbook.bids and orderbook.asks:
best_bid = orderbook.bids[0].price / 10000
best_ask = orderbook.asks[0].price / 10000
spread = best_ask - best_bid
print(f"Orderbook:")
print(f" Bid: {best_bid:.2f}%")
print(f" Ask: {best_ask:.2f}%")
print(f" Spread: {spread:.2f}%\n")
# Stats
print(f"Statistics:")
print(f" 24h Volume: ${stats.volume_24h / 1e6:,.2f}")
print(f" Last Price: {stats.last_price / 10000:.2f}%")
print(f" Trades: {stats.num_trades}\n")
# Recent trades
print(f"Recent Trades:")
for trade in trades[:5]:
price_pct = trade.price / 10000
shares = trade.size / 1_000_000
outcome = "YES" if trade.outcome == 0 else "NO"
timestamp = time.strftime('%H:%M:%S', time.localtime(trade.timestamp))
print(f" {timestamp}: {shares:.2f} {outcome} @ {price_pct:.2f}%")
except Exception as e:
print(f"Error: {e}")
time.sleep(5)
if __name__ == "__main__":
# Monitor the current BTC quick market
market = client.get_quick_market("BTC")
monitor_market(market.market_id)
Next Steps
WebSocket Streams
Get real-time market updates
Build a Trading Bot
Automate trading with a bot
API Reference
Complete API documentation
First Trade
Learn the basics of trading