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}")

Parameter	Type	Required	Description
chain_id	int	No	Filter by chain ID

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")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID (hex string)

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}")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID
outcome	Outcome	No	Filter by Outcome.YES or Outcome.NO

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}")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID
limit	int	No	Max trades to return (default: 100)

Returns: list[Trade]

get_stats

Get statistics for a market. Alias for get_market.

Parameter	Type	Required	Description
market_id	str	Yes	Market ID

Returns: MarketStats

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}")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID
limit	int	No	Max holders to return (default: 100)

Returns: list[Holder]

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}")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID

Returns: Resolution

get_health

Check API server health.

health = client.get_health()
print(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}")

Parameter	Type	Required	Description
asset	str	Yes	Asset symbol ("BTC", "ETH")

Returns: QuickMarket

get_quick_market_history

Get historical quick markets for an asset.

history = client.get_quick_market_history("BTC", limit=10)

for qm in history:
    outcome = "YES" if qm.outcome == 0 else ("NO" if qm.outcome == 1 else "N/A")
    print(f"ID={qm.id} | resolved={qm.resolved} | outcome={outcome}")

Parameter	Type	Required	Description
asset	str	Yes	Asset symbol
limit	int	No	Max markets to return (default: 100)

Returns: list[QuickMarket]

get_quick_market_price

Get the current price for an asset.

price = client.get_quick_market_price("BTC")
print(f"BTC: ${price.price / 1e8:,.2f}")

Parameter	Type	Required	Description
asset	str	Yes	Asset symbol

Returns: AssetPrice

get_quick_market_price_history

Get price history for an asset.

prices = client.get_quick_market_price_history("BTC", limit=60)

for p in prices:
    print(f"  {p.timestamp}: ${p.price / 1e8:,.2f}")

Parameter	Type	Required	Description
asset	str	Yes	Asset symbol
limit	int	No	Max prices to return (default: 100)

Returns: list[AssetPrice]

get_failed_trades

Get all failed trade settlements.

failed = client.get_failed_trades()
for t in failed:
    print(f"tx={t.tx_hash} | reason={t.reason} | size={t.fill_size}")

Returns: list[FailedTrade]

get_pending_trades

Get all pending trade settlements.

pending = client.get_pending_trades()
for t in pending:
    print(f"tx={t.tx_hash} | size={t.fill_size} | batch={t.is_batch}")

Returns: list[PendingTrade]

get_failed_claims

Get all failed redemption claims.

Returns: list[FailedClaim]

get_pending_claims

Get all pending redemption claims.

Returns: 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}")

Parameter	Type	Required	Description
tx_hash	str	Yes	Transaction hash

Returns: SettlementStatus

---

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}")

Parameter	Type	Required	Description
order_args	OrderArgs	Yes	Order parameters
settlement_address	str	No	Override settlement address (auto-fetched from market if omitted)

Returns: SignedOrder

create_limit_buy

Convenience method for creating a signed buy order.

signed = client.create_limit_buy(
    market_id="0x...",
    outcome=Outcome.YES,
    price=450000,       # $0.45
    size=5000000,       # 5 shares
    expiration=int(time.time()) + 3600,
)

Parameter	Type	Required	Description
market_id	str	Yes	Market ID
outcome	Outcome	Yes	Outcome.YES or Outcome.NO
price	int	Yes	Price (1–999999, where 500000 = $0.50)
size	int	Yes	Size in shares (6 decimals; 1000000 = 1 share)
expiration	int	No	Unix timestamp (default: 1 hour from now)
settlement_address	str	No	Override settlement address

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.

signed = client.create_limit_buy(
    market_id="0x...",
    outcome=Outcome.YES,
    price=500000,
    size=1000000,
)

result = client.post_order(signed)
print(f"Response: {result}")

Parameter	Type	Required	Description
signed_order	SignedOrder	Yes	A signed order

Returns: dict — API response with match/fill details

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}")

Parameter	Type	Required	Description
trader	str	No	Filter by trader address
market_id	str	No	Filter by market ID
status	str	No	Filter: "open", "filled", "cancelled"

Returns: list[Order]

get_order

Get a specific order by hash.

order = client.get_order("0xOrderHash...")
print(f"Status: {order.status} | Filled: {order.filled_size / 1e6:.2f} / {order.size / 1e6:.2f}")

Parameter	Type	Required	Description
order_hash	str	Yes	The order hash

Returns: Order

cancel_order

Cancel a single order.

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

Parameter	Type	Required	Description
order_hash	str	Yes	The order hash
market_id	str	No	Market ID (for validation)
side	Side	No	Order side (for validation)

Returns: dict

cancel_market_orders

Cancel all your orders for a market.

result = client.cancel_market_orders(market_id="0x...")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID

Returns: dict

get_positions

Get positions for a market, optionally filtered by user.

positions = client.get_positions(market_id="0x...", user_address="0x...")

for p in positions:
    print(f"YES: {p.yes_shares / 1e6:.2f} shares (cost: {p.yes_cost / 1e6:.2f} USDC)")
    print(f"NO:  {p.no_shares / 1e6:.2f} shares (cost: {p.no_cost / 1e6:.2f} USDC)")

Parameter	Type	Required	Description
market_id	str	Yes	Market ID
user_address	str	No	Filter by user address

Returns: list[Position]

get_user_positions

Get all positions across markets for a user.

positions = client.get_user_positions(address="0x...", chain_id=137)

for p in positions:
    print(f"Market {p.market_id[:16]}... | YES={p.yes_shares / 1e6:.2f} | NO={p.no_shares / 1e6:.2f}")

Parameter	Type	Required	Description
address	str	Yes	User address
chain_id	int	No	Filter by chain ID

Returns: list[Position]

get_user_orders

Get all orders for a user.

Parameter	Type	Required	Description
address	str	Yes	User address
status	str	No	Filter: "open", "filled", "cancelled"

Returns: list[Order]

get_user_activity

Get trading activity summary for a user.

activity = client.get_user_activity("0x...")

print(f"Total trades: {activity.total_trades}")
print(f"Total volume: {activity.total_volume / 1e6:.2f} USDC")
print(f"PNL: {activity.pnl / 1e6:.2f} USDC")
print(f"Markets traded: {activity.markets_traded}")

Parameter	Type	Required	Description
address	str	Yes	User address

Returns: UserActivity

get_user_stats

Get statistics for the authenticated user.

stats = client.get_user_stats()

print(f"Total cost: {stats.total_cost / 1e6:.2f} USDC")
print(f"Position value: {stats.position_value / 1e6:.2f} USDC")
print(f"PNL: {stats.pnl / 1e6:.2f} USDC ({stats.pnl_percentage:.1f}%)")

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 — all future orders reuse the allowance.

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

# With explicit settlement address
result = client.approve_usdc_for_settlement(
    settlement_address="0xdB96C91d9e5930fE3Ed1604603CfA4ece454725c"
)

Parameter	Type	Required	Description
settlement_address	str	No	Settlement contract (defaults to chain config)

Returns: dict — Relayer response with tx_hash

approve_ctf_for_settlement

Sign and submit a gasless CTF SetApprovalForAll permit to let the settlement contract transfer your conditional tokens.

result = client.approve_ctf_for_settlement()

Parameter	Type	Required	Description
settlement_address	str	No	Settlement contract (defaults to chain config)

Returns: dict — Relayer response with tx_hash

sign_usdc_permit

Sign an EIP-2612 permit for a specific USDC amount. Use this for per-order permits instead of the max permit.

permit = client.sign_usdc_permit(
    value=10000000,  # $10 USDC
)

# Attach to a signed order before submission
signed_order.permit_signature = permit
result = client.post_order(signed_order)

Parameter	Type	Required	Description
value	int	Yes	Amount to approve (6 decimals; 1000000 = $1 USDC)
settlement_address	str	No	Spender address (defaults to chain config)
deadline	int	No	Expiration timestamp (default: 1 hour from now)

Returns: PermitSignature

approve_usdc

On-chain USDC approval (requires native gas). Alternative to permit-based approval for high-frequency scenarios.

tx_hash = client.approve_usdc(amount=2**256 - 1)  # Max approval
print(f"TX: {tx_hash}")

Parameter	Type	Required	Description
amount	int	Yes	Amount to approve (6 decimals)
spender	str	No	Spender address (defaults to settlement)

Returns: str — Transaction hash

get_usdc_allowance

Query the current USDC allowance for a spender.

allowance = client.get_usdc_allowance()
print(f"Allowance: {allowance / 1e6:.2f} USDC")

Parameter	Type	Required	Description
owner	str	No	Token owner (defaults to signer address)
spender	str	No	Spender (defaults to settlement contract)

Returns: int — Allowance in USDC (6 decimals)

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:

1

Query on-chain

Queries the market contract on-chain for resolution status and condition data.

2

Check balance

Checks your balance of the winning token.

3

Sign permit

Signs an EIP-712 RedeemPositions permit.

4

Submit to relayer

Submits to the relayer for gasless execution.

Parameter	Type	Required	Description
market_contract_address	str	Yes	The market's contract address (not market ID)

Returns: dict — Relayer response with tx_hash

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...",
])
print(f"TX: {result}")

Markets that are not resolved or where you have no winning tokens are skipped automatically.

Parameter	Type	Required	Description
market_contract_addresses	list[str]	Yes	List of market contract addresses

Returns: dict — Relayer response with txHash

sync_permit_nonce

Resync the local permit nonce with the blockchain. Use after a permit failure or when nonces get out of sync.

nonce = client.sync_permit_nonce()
print(f"On-chain nonce: {nonce}")

Parameter	Type	Required	Description
contract_address	str	No	Token contract (defaults to USDC)

Returns: int — The current on-chain nonce

---

Static Methods

request_api_credentials

Register for API credentials by proving wallet ownership. This is a static method — no client instance needed.

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']}")

Parameter	Type	Required	Description
host	str	Yes	API base URL
private_key	str	Yes	Wallet private key
name	str	No	Friendly name for the API key

Returns: dict with api_key_id, api_private_key, message

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