Client Reference

Complete reference for all TurbineClient methods, organized by access level.

Public Data (No Auth)

These methods work with any client, including read-only clients with no credentials.

get_markets

Fetch all markets, optionally filtered by chain.

markets = client.get_markets()
markets = client.get_markets(chain_id=137)

for m in markets:
    print(f"{m.question} | volume={m.volume / 1e6:.2f} USDC | resolved={m.resolved}")

Returns: list[Market]

get_market

Get stats for a single market.

stats = client.get_market(market_id="0x...")

print(f"Last price: {stats.last_price / 1e6:.4f} (${stats.last_price / 1e6:.4f})")
print(f"24h volume: {stats.volume_24h / 1e6:.2f} USDC")
print(f"Total volume: {stats.total_volume / 1e6:.2f} USDC")

Returns: MarketStats

get_orderbook

Get the orderbook snapshot for a market, optionally filtered by outcome.

# Full orderbook (both outcomes)
ob = client.get_orderbook("0x...")

# YES side only
yes_ob = client.get_orderbook("0x...", outcome=Outcome.YES)

# Print top of book
if yes_ob.bids:
    best_bid = yes_ob.bids[0]
    print(f"Best bid: {best_bid.price} (${best_bid.price / 1e6:.4f}) x {best_bid.size / 1e6:.2f}")
if yes_ob.asks:
    best_ask = yes_ob.asks[0]
    print(f"Best ask: {best_ask.price} (${best_ask.price / 1e6:.4f}) x {best_ask.size / 1e6:.2f}")

Returns: OrderBookSnapshot

get_trades

Get recent trades for a market.

trades = client.get_trades("0x...", limit=50)

for t in trades:
    side = "BUY" if t.outcome == 0 else "SELL"
    print(f"{side} {t.size / 1e6:.2f} @ {t.price} (${t.price / 1e6:.4f}) | tx={t.tx_hash}")

Returns: list[Trade]

get_stats

Get statistics for a market. Alias for get_market.

get_platform_stats

Get platform-wide statistics across all chains.

stats = client.get_platform_stats()

print(f"Total volume: {stats.total_volume / 1e6:.2f} USDC")
print(f"Total trades: {stats.total_trades}")

for chain in stats.chains:
    print(f"  Chain {chain.chain_id}: {chain.total_volume / 1e6:.2f} USDC")

Returns: PlatformStats

get_holders

Get top position holders for a market.

holders = client.get_holders("0x...", limit=10)

for h in holders:
    print(f"{h.user_address}: YES={h.yes_shares / 1e6:.2f}, NO={h.no_shares / 1e6:.2f}")

get_resolution

Get resolution status for a market.

res = client.get_resolution("0x...")

print(f"Resolved: {res.resolved}")
if res.resolved:
    outcome = "YES" if res.outcome == 0 else "NO"
    print(f"Winner: {outcome}")
    print(f"Assertion ID: {res.assertion_id}")

get_health

Check API server health. Returns: dict

get_quick_market

Get the active quick market for an asset.

qm = client.get_quick_market("BTC")

print(f"Market ID: {qm.market_id}")
print(f"Strike: ${qm.start_price / 1e8:,.2f}")
print(f"Ends: {qm.end_time}")
print(f"Contract: {qm.contract_address}")

get_quick_market_history

Get historical quick markets for an asset.

get_quick_market_price

Get the current price for an asset. Returns: AssetPrice

get_quick_market_price_history

Get price history for an asset. Returns: list[AssetPrice]

get_failed_trades / get_pending_trades

Get failed or pending trade settlements. Returns: list[FailedTrade] / list[PendingTrade]

get_failed_claims / get_pending_claims

Get failed or pending redemption claims. Returns: list[FailedClaim] / list[PendingClaim]

get_settlement_status

Check the settlement status for a specific transaction.

status = client.get_settlement_status("0xTxHash...")

print(f"Found: {status.found}")
print(f"Status: {status.status}")
print(f"Error: {status.error}")

Order Management (Requires Signing)

These methods require a private_key in the client constructor (Level 1+).

create_order

Create and sign an order from an OrderArgs object.

from turbine_client import OrderArgs, Outcome, Side
import time

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

signed = client.create_order(args)
print(f"Order hash: {signed.order_hash}")
print(f"Signature: {signed.signature}")

create_limit_buy

Convenience method for creating a signed buy order.

Returns: SignedOrder

create_limit_sell

Same parameters and behavior as create_limit_buy, but creates a sell order. Returns: SignedOrder

Authenticated Endpoints (Requires Bearer Token)

These methods require api_key_id + api_private_key (Level 2). Bearer tokens are generated automatically per request.

post_order

Submit a signed order to the orderbook. Returns: dict

get_orders

Get orders, optionally filtered.

# All open orders for a market
orders = client.get_orders(market_id="0x...", status="open")

# All orders by a specific trader
orders = client.get_orders(trader="0xAddress...")

for o in orders:
    side = "BUY" if o.side == 0 else "SELL"
    outcome = "YES" if o.outcome == 0 else "NO"
    print(f"{side} {outcome} | {o.remaining_size / 1e6:.2f} @ {o.price} (${o.price / 1e6:.4f}) | {o.status}")

get_order

Get a specific order by hash. Returns: Order

cancel_order

Cancel a single order.

result = client.cancel_order(
    order_hash="0x...",
    market_id="0x...",    # optional
    side=Side.BUY,        # optional
)

cancel_market_orders

Cancel all your orders for a market.

get_positions

Get positions for a market, optionally filtered by user.

get_user_positions

Get all positions across markets for a user.

get_user_orders

Get all orders for a user.

get_user_activity

Get trading activity summary for a user. Returns: UserActivity

get_user_stats

Get statistics for the authenticated user. Returns: UserStats

Gasless / Relayer Operations

These methods sign EIP-712 permits and submit them to the relayer for gasless execution. Requires Level 2 access (private key + API credentials). No native gas tokens are needed.

approve_usdc_for_settlement

Sign and submit a gasless max USDC permit. One-time per settlement contract.

result = client.approve_usdc_for_settlement()
print(f"TX: {result}")

approve_ctf_for_settlement

Sign and submit a gasless CTF SetApprovalForAll permit.

sign_usdc_permit

Sign an EIP-2612 permit for a specific USDC amount. Returns: PermitSignature

approve_usdc

On-chain USDC approval (requires native gas). Returns: str (transaction hash)

get_usdc_allowance

Query the current USDC allowance for a spender. Returns: int

claim_winnings

Claim winnings from a single resolved market via gasless permit.

result = client.claim_winnings(
    market_contract_address="0xMarketContractAddress..."
)
print(f"TX: {result}")

This method queries on-chain state, checks your balance, signs a permit, and submits to the relayer. Raises ValueError if the market is not resolved or you have no winning tokens.

batch_claim_winnings

Claim winnings from multiple resolved markets in a single batch transaction.

result = client.batch_claim_winnings([
    "0xMarket1ContractAddress...",
    "0xMarket2ContractAddress...",
    "0xMarket3ContractAddress...",
])

sync_permit_nonce

Resync the local permit nonce with the blockchain. Returns: int

Static Methods

request_api_credentials

Register for API credentials by proving wallet ownership.

creds = TurbineClient.request_api_credentials(
    host="https://api.turbinefi.com",
    private_key="0xYourPrivateKey",
    name="my-trading-bot",  # optional
)

print(f"Key ID: {creds['api_key_id']}")
print(f"Private Key: {creds['api_private_key']}")

Raises: TurbineApiError with status 409 if the wallet already has a key.