SDK VERSION
v0.1.0
SERVICES
10
LANGUAGE
PYTHON

[ PYTHON SDK ]

Official Python SDK for Event Trader prediction markets. Async-first, type-safe, and designed for professional trading bots.

pip install event-trader

[ INSTALLATION ]

Basic Installation

pip install event-trader

With Web3 Support

pip install event-trader[web3]

Requirements

  • Python 3.10+
  • httpx (async HTTP client)
  • pydantic v2 (data validation)
  • websockets (real-time streaming)

[ QUICK START ]

Get started with Event Trader SDK in just a few lines of code:

Python
import asyncio
from event_trader import EventTrader

async def main():
    # Initialize with API key
    async with EventTrader(api_key="evt_...") as client:
        # List active markets
        markets = await client.markets.list(status="active")
        for market in markets:
            print(f"{market.question} - {market.status}")

        # Get order book
        orderbook = await client.markets.orderbook(markets[0].id, "BTC")
        print(f"Best bid: {orderbook.best_bid}, Best ask: {orderbook.best_ask}")

        # Place an order
        order = await client.trading.place_order(
            market_id=markets[0].id,
            asset="BTC",
            side="buy",
            price=0.65,
            quantity=100,
        )
        print(f"Order placed: {order.id}")

asyncio.run(main())

Key Features

Async/Await Type-Safe Auto-Reconnect Rate Limiting JWT Auto-Refresh WebSocket Streaming

[ AUTHENTICATION ]

The SDK supports three authentication methods:

API Key

Simplest method - recommended for server-side applications:

Python
from event_trader import EventTrader

client = EventTrader(api_key="evt_your_api_key_here")
# Or use environment variable
# export EVENT_TRADER_API_KEY=evt_...
client = EventTrader()  # Auto-reads from env

Email/Password (JWT)

User authentication with automatic token refresh:

Python
from event_trader import EventTrader

# Login with credentials
client = await EventTrader.from_credentials(
    email="user@example.com",
    password="your_password",
)

# Tokens refresh automatically before expiration

Wallet (SIWE)

Sign-In With Ethereum for Web3-native authentication:

Python
from event_trader import EventTrader

# Define your signing callback
async def sign_message(message: str) -> str:
    # Use your wallet library to sign
    return wallet.sign_message(message)

# Authenticate with wallet
client = await EventTrader.from_wallet(
    wallet_address="0x742d35Cc6634C0532925a3b844Bc9e7595f3E6",
    sign_callback=sign_message,
)

[ SERVICES ]

The SDK provides 10 specialized services for different platform features:

📈 Markets

List, search, and get details on prediction markets and orderbooks

list() get() orderbook() featured()

💰 Trading

Place orders, manage positions, and view trade history

place_order() cancel_order() open_orders() history()

Streaming

Real-time WebSocket streams for orderbooks and prices

orderbook() prices() trades()

🏆 Incentives

Bot management, rewards tracking, and leaderboards

register_bot() tier_status() earnings() leaderboard()

🔒 Staking

Stake tokens for rewards, lockup tiers, and voting power

stake() unstake() claim_rewards() get_summary()

🎮 Games

Gamification features: streaks, duels, tournaments

record_streak() create_duel() join_tournament() activate_boost()

👛 Wallet

Multi-wallet support, SIWE auth, portfolio tracking

connect() portfolio() gas_recommendations()

🔗 DeFi

DEX aggregation, impermanent loss calculator, MEV protection

swap_quote() calculate_il() assess_mev_risk()

💲 Exchanges

Unified CEX interface for Binance, Coinbase, Kraken

ticker() place_limit_order() compare_tickers()

📊 Aggregator

Cross-platform markets and arbitrage detection

markets() arbitrage_opportunities() route_order()

💵 Prices

Token prices, historical data, and conversions

get() bulk() historical() convert()

[ MARKETS SERVICE ]

Access prediction markets data, orderbooks, and market details.

List Markets

Python
# List all active markets
markets = await client.markets.list(status="active", limit=50)

# Filter by asset type
crypto_markets = await client.markets.list(
    status="active",
    asset_type="crypto",
)

# Search markets
results = await client.markets.search("bitcoin ETF")

for market in markets:
    print(f"{market.id}: {market.question}")
    print(f"  Status: {market.status}")
    print(f"  Volume: ${market.total_volume}")

Get Order Book

Python
# Get orderbook for specific asset
orderbook = await client.markets.orderbook(
    market_id="0x123...",
    asset="BTC",
)

print(f"Best Bid: {orderbook.best_bid}")
print(f"Best Ask: {orderbook.best_ask}")
print(f"Spread: {orderbook.spread}")

# Iterate through price levels
for bid in orderbook.bids[:5]:
    print(f"  BID: {bid.price} x {bid.quantity}")

Featured Market

Python
# Get the featured market
featured = await client.markets.featured()
print(f"Featured: {featured.question}")
print(f"Total Volume: ${featured.total_volume}")

[ TRADING SERVICE ]

Place orders, manage positions, and track trade history.

Place Order

Python
# Place a limit buy order
order = await client.trading.place_order(
    market_id="0x123...",
    asset="BTC",
    side="buy",
    price=0.65,      # 65 cents per share
    quantity=100,    # 100 shares
)

print(f"Order ID: {order.id}")
print(f"Status: {order.status}")
print(f"Filled: {order.filled_quantity}/{order.quantity}")

Cancel Order

Python
# Cancel a specific order
await client.trading.cancel_order(order_id="order_123")

# Cancel all orders for a market
await client.trading.cancel_all(market_id="0x123...")

Open Orders & History

Python
# Get all open orders
open_orders = await client.trading.open_orders()
for order in open_orders:
    print(f"{order.side} {order.quantity} @ {order.price}")

# Get trade history
trades = await client.trading.history(
    market_id="0x123...",
    limit=100,
)

# Get current positions
positions = await client.trading.positions()
for pos in positions:
    print(f"{pos.market_id}: {pos.quantity} shares @ {pos.avg_price}")

[ STREAMING SERVICE ]

Real-time WebSocket streams with automatic reconnection.

Stream Order Book

Python
# Stream orderbook updates in real-time
async for update in client.streaming.orderbook("0x123...", "BTC"):
    print(f"Spread: {update.spread}")
    print(f"Best Bid: {update.best_bid}")
    print(f"Best Ask: {update.best_ask}")

    # Process your trading logic here
    if update.spread > 0.05:
        print("Wide spread detected!")

Stream Prices

Python
# Stream price updates for multiple assets
async for price in client.streaming.prices(["BTC", "ETH", "SOL"]):
    print(f"{price.symbol}: ${price.price} ({price.change_24h}%)")

Stream Trades

Python
# Stream live trades as they happen
async for trade in client.streaming.trades("0x123..."):
    emoji = "🟢" if trade.side == "buy" else "🔴"
    print(f"{emoji} {trade.quantity} @ {trade.price}")

[ INCENTIVES SERVICE ]

Bot management, rewards tracking, and competitive leaderboards.

Register Bot

Python
# Register a new trading bot
bot = await client.incentives.register_bot(
    name="MyArbitrageBot",
    wallet_address="0x742d35Cc6634C0532925a3b844Bc9e7595f3E6",
    strategy_type="arbitrage",
    description="Cross-market arbitrage bot",
)

print(f"Bot ID: {bot.id}")
print(f"API Key: {bot.api_key}")  # Save this!

Track Volume & Rewards

Python
# Record trading volume
await client.incentives.record_volume(
    bot_id=bot.id,
    market_id="0x123...",
    volume_usd=5000,
)

# Check tier status
tier = await client.incentives.tier_status(bot.id)
print(f"Current Tier: {tier.current_tier}")
print(f"Reward Multiplier: {tier.reward_multiplier}x")
print(f"Volume to Next Tier: ${tier.volume_to_next_tier}")

# Get earnings breakdown
earnings = await client.incentives.earnings(bot.id)
print(f"Total Earned: ${earnings.total_earned}")
print(f"Pending: ${earnings.pending}")

Leaderboard

Python
# Get weekly leaderboard
leaderboard = await client.incentives.leaderboard(
    period="weekly",
    limit=10,
)

for entry in leaderboard:
    print(f"#{entry.rank} {entry.bot_name}: ${entry.volume}")

[ STAKING SERVICE ]

Lock tokens to earn yield with configurable lockup periods and bonus APY.

List Staking Pools

Python
# List available staking pools
pools = await client.incentives.list_staking_pools()

for pool in pools:
    print(f"{pool.name}")
    print(f"  Token: {pool.stake_token.symbol}")
    print(f"  Base APY: {pool.apy.base}%")
    print(f"  Max APY: {pool.apy.max}%")
    print(f"  Total Staked: {pool.pool_stats.total_staked}")
    print(f"  Lockup Tiers: {len(pool.lockup_tiers)}")

Stake Tokens

Python
# Stake tokens with 90-day lockup for bonus APY
stake = await client.incentives.stake(
    pool_id="pool_abc123",
    wallet="0x742d35Cc6634C0532925a3b844Bc9e7595f3E6",
    amount=1000,
    lockup_days=90,  # Lock for 90 days to get bonus APY
)

print(f"Stake ID: {stake.stake_id}")
print(f"Amount: {stake.amount}")
print(f"Effective APY: {stake.effective_apy}%")
print(f"Voting Power: {stake.voting_power}")
print(f"Lockup Ends: {stake.timing.lockup_ends_at}")

Check & Claim Rewards

Python
# Calculate pending rewards
rewards = await client.incentives.calculate_staking_rewards(stake.stake_id)
print(f"Pending Rewards: {rewards.pending_rewards}")
print(f"Days Elapsed: {rewards.days_elapsed}")

# Claim rewards
claim = await client.incentives.claim_staking_rewards(
    stake_id=stake.stake_id,
    wallet="0x...",
)
print(f"Claimed: {claim.amount} {claim.reward_token.symbol}")

Unstaking

Python
# Request unstake (starts cooldown period)
stake = await client.incentives.request_unstake(
    stake_id="stake_123",
    wallet="0x...",
)
print(f"Cooldown ends: {stake.timing.cooldown_ends_at}")

# Complete unstake after cooldown
stake = await client.incentives.complete_unstake(
    stake_id="stake_123",
    wallet="0x...",
)
print(f"Unstaked! Status: {stake.status}")

# Emergency unstake (with penalty)
stake = await client.incentives.emergency_unstake(
    stake_id="stake_456",
    wallet="0x...",
)
print(f"Penalty applied: {stake.penalty_applied}")

User Staking Summary

Python
# Get full staking summary for a user
summary = await client.incentives.get_staking_summary("0x...")

print(f"Total Staked: {summary.total_staked}")
print(f"Active Stakes: {summary.active_stakes}")
print(f"Pending Rewards: {summary.pending_rewards}")
print(f"Total Claimed: {summary.total_claimed}")
print(f"Voting Power: {summary.total_voting_power}")

# List individual stakes
for stake in summary.stakes:
    print(f"  {stake.stake_id}: {stake.amount} @ {stake.effective_apy}% APY")

Lockup Tiers

Longer lockup periods earn higher APY:

Lockup Bonus APY Voting Power
Flexible (0 days) +0% 1.0x
30 days +5% 1.25x
90 days +15% 1.5x
180 days +25% 2.0x
365 days +40% 3.0x

[ GAMES SERVICE ]

Gamification features to increase engagement and rewards.

Win Streaks

Python
# Record a winning trade
streak = await client.games.record_streak(
    user_id="user_123",
    result="win",
    market_id="0x123...",
)

print(f"Current Streak: {streak.current_count} wins")
print(f"Bonus Multiplier: {streak.bonus_multiplier}x")

# Get streak bonus
bonus = await client.games.streak_bonus("user_123")
print(f"Your Bonus: {bonus.bonus_percent}%")

Duels

Python
# Create a trading duel
duel = await client.games.create_duel(
    market_id="0x123...",
    stake_amount=100,
    duration_hours=24,
)

print(f"Duel ID: {duel.id}")
print(f"Prize Pool: ${duel.prize_pool}")

# Accept a duel challenge
await client.games.accept_duel(duel_id=duel.id, user_id="user_456")

Tournaments

Python
# List active tournaments
tournaments = await client.games.list_tournaments(status="active")

for t in tournaments:
    print(f"{t.name}: ${t.prize_pool} prize pool")
    print(f"  {t.current_participants}/{t.max_participants} joined")

# Join a tournament
entry = await client.games.join_tournament(
    tournament_id=tournaments[0].id,
    user_id="user_123",
)

# Check tournament leaderboard
leaderboard = await client.games.tournament_leaderboard(
    tournament_id=tournaments[0].id,
    limit=10,
)

Boosts

Python
# Get available boosts
boosts = await client.games.available_boosts("user_123")

# Activate XP boost
activation = await client.games.activate_boost("user_123", "xp_boost")
print(f"Boost: {activation.multiplier}x for {activation.duration}")

[ WALLET SERVICE ]

Multi-wallet support, portfolio tracking, and gas estimation.

Portfolio

Python
# Get wallet portfolio
portfolio = await client.wallet.portfolio(
    address="0x742d35Cc6634C0532925a3b844Bc9e7595f3E6",
    chain="polygon",
)

print(f"Native Balance: {portfolio.native_balance} MATIC")
print(f"Tokens: {len(portfolio.tokens)}")

for token in portfolio.tokens:
    print(f"  {token.symbol}: {token.balance} (${token.value_usd})")

Gas Recommendations

Python
# Get gas price recommendations
gas = await client.wallet.gas_recommendations(chain="ethereum")

print(f"Slow: {gas.slow.gwei} gwei (~{gas.slow.estimated_time})")
print(f"Standard: {gas.standard.gwei} gwei (~{gas.standard.estimated_time})")
print(f"Fast: {gas.fast.gwei} gwei (~{gas.fast.estimated_time})")

SIWE Authentication

Python
# Full SIWE authentication flow
session = await client.wallet.siwe_authenticate(
    address="0x742d35Cc6634C0532925a3b844Bc9e7595f3E6",
    sign_callback=your_sign_function,
    chain_id=137,  # Polygon
)

print(f"Session: {session.session_id}")
print(f"Expires: {session.expires_at}")

[ DEFI SERVICE ]

DEX aggregation, impermanent loss calculator, and MEV protection.

Swap Quote

Python
# Get best swap quote across DEXs
quote = await client.defi.swap_quote(
    token_in="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",  # WETH
    token_out="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", # USDC
    amount_in="1000000000000000000",  # 1 ETH in wei
    chain="ethereum",
    slippage_bps=50,
)

print(f"Output: {quote.amount_out} USDC")
print(f"Price Impact: {quote.price_impact_pct}%")
print(f"Route: {' -> '.join(quote.route)}")

Impermanent Loss Calculator

Python
# Calculate IL for LP position
il = await client.defi.calculate_il(
    pool_address="0x8ad599c3A0ff1De082011EFDDc58f1908eb6e6D8",
    token_a="WETH",
    token_b="USDC",
    initial_price="2000",
    current_price="2500",
    initial_value_usd="10000",
    fees_earned_usd="150",
)

print(f"Impermanent Loss: {il.impermanent_loss_pct}%")
print(f"Hold Value: ${il.hold_value_usd}")
print(f"LP Value: ${il.lp_value_usd}")
print(f"Net vs Hold: ${il.net_pnl_vs_hold_usd}")

MEV Risk Assessment

Python
# Assess MEV risk for large swap
mev = await client.defi.assess_mev_risk(
    token_in="0xWETH...",
    token_out="0xUSDC...",
    amount_in="10000000000000000000",  # 10 ETH
    amount_in_usd="25000",
    slippage_bps=100,
)

print(f"Risk Score: {mev.risk_score}/100")
print(f"Risk Level: {mev.risk_level}")
print(f"Estimated MEV: ${mev.estimated_mev_usd}")
print(f"Attack Vectors: {mev.attack_vectors}")
print(f"Recommended: {mev.recommended_protection}")

[ EXCHANGES SERVICE ]

Unified interface for centralized exchanges (Binance, Coinbase, Kraken, etc.).

Market Data

Python
# Get ticker from Binance
ticker = await client.exchanges.ticker("binance", "BTC/USDT")

print(f"Last: ${ticker.last}")
print(f"Bid: ${ticker.bid} / Ask: ${ticker.ask}")
print(f"24h Volume: {ticker.volume_24h} BTC")
print(f"24h Change: {ticker.change_pct_24h}%")

Cross-Exchange Comparison

Python
# Compare prices across exchanges
comparison = await client.exchanges.compare_tickers(
    "BTC/USDT",
    exchanges=["binance", "coinbase", "kraken"],
)

for exchange, data in comparison.exchanges.items():
    print(f"{exchange}: Bid ${data.bid} / Ask ${data.ask}")

print(f"Best Bid: {comparison.best_bid['exchange']} @ ${comparison.best_bid['price']}")
print(f"Best Ask: {comparison.best_ask['exchange']} @ ${comparison.best_ask['price']}")

if comparison.arbitrage_opportunity:
    print("⚠️ Arbitrage opportunity detected!")

Trading

Python
# Place limit order on Binance
order = await client.exchanges.place_limit_order(
    exchange="binance",
    symbol="BTC/USDT",
    side="buy",
    amount=0.001,
    price=50000,
)

print(f"Order ID: {order.order_id}")
print(f"Status: {order.status}")

# Get account balance
balance = await client.exchanges.balance("binance", assets=["BTC", "USDT"])
for asset, bal in balance.balances.items():
    print(f"{asset}: {bal.free} free, {bal.used} in orders")

[ AGGREGATOR SERVICE ]

Cross-platform prediction markets aggregation and arbitrage detection.

Cross-Platform Markets

Python
# Get markets across platforms
markets = await client.aggregator.markets(
    platforms=["polymarket", "kalshi"],
    category="politics",
)

for market in markets:
    print(f"{market.question}")
    print(f"  Platform: {market.platform}")
    print(f"  Volume: ${market.volume}")

Arbitrage Detection

Python
# Find arbitrage opportunities
arbs = await client.aggregator.arbitrage_opportunities(
    min_spread_bps=20,
    min_profit=1.0,
)

for arb in arbs:
    print(f"Opportunity: {arb.market_question}")
    print(f"  Buy on: {arb.buy_platform} @ {arb.buy_price}")
    print(f"  Sell on: {arb.sell_platform} @ {arb.sell_price}")
    print(f"  Profit: ${arb.expected_profit}")

Smart Order Routing

Python
# Get optimal execution plan
plan = await client.aggregator.route_order(
    market_id="0x123...",
    outcome_id="Yes",
    side="buy",
    size=1000,
    strategy="best_price",
)

print(f"Total Cost: ${plan.total_cost}")
print(f"Avg Price: {plan.average_price}")
for leg in plan.legs:
    print(f"  {leg.platform}: {leg.quantity} @ {leg.price}")

[ ERROR HANDLING ]

The SDK provides a comprehensive error hierarchy for granular exception handling:

EventTraderError - Base exception
APIError - General API errors
AuthenticationError - Auth failures
RateLimitError - Rate limit exceeded
ValidationError - Invalid parameters
NotFoundError - Resource not found
ConnectionError - Network issues
TimeoutError - Request timeout
WebSocketError - WS issues
InsufficientFundsError - Low balance
OrderError - Order failures
MarketClosedError - Market closed

Example

Python
from event_trader import (
    EventTrader,
    EventTraderError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    InsufficientFundsError,
    OrderError,
)

try:
    order = await client.trading.place_order(
        market_id="0x123...",
        asset="BTC",
        side="buy",
        price=0.65,
        quantity=100,
    )
except InsufficientFundsError:
    print("Not enough balance to place order")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except NotFoundError:
    print("Market not found")
except OrderError as e:
    print(f"Order failed: {e.message}")
except EventTraderError as e:
    print(f"SDK error: {e}")

[ EXAMPLES ]

Complete working examples are available in the SDK repository:

Example Description
basic_trading.py Basic trading workflow - list markets, place orders
streaming_orderbook.py Real-time orderbook streaming with WebSocket
market_maker_bot.py Simple market maker with spread management
bot_incentives.py Bot registration, rewards, and leaderboards
gamification.py Streaks, duels, tournaments, and boosts
defi_integration.py DEX quotes, IL calculation, MEV protection
exchange_trading.py CEX trading with Binance, Coinbase, Kraken

Market Maker Bot Example

Python
import asyncio
from event_trader import EventTrader

async def market_maker():
    async with EventTrader(api_key="evt_...") as client:
        market_id = "0x123..."
        asset = "BTC"
        spread = 0.02  # 2% spread
        size = 100

        while True:
            # Get current orderbook
            ob = await client.markets.orderbook(market_id, asset)
            mid_price = (ob.best_bid + ob.best_ask) / 2

            # Cancel existing orders
            await client.trading.cancel_all(market_id=market_id)

            # Place new orders around mid price
            bid_price = mid_price * (1 - spread / 2)
            ask_price = mid_price * (1 + spread / 2)

            await client.trading.place_order(
                market_id=market_id,
                asset=asset,
                side="buy",
                price=bid_price,
                quantity=size,
            )

            await client.trading.place_order(
                market_id=market_id,
                asset=asset,
                side="sell",
                price=ask_price,
                quantity=size,
            )

            print(f"Quotes: {bid_price:.4f} / {ask_price:.4f}")
            await asyncio.sleep(5)

asyncio.run(market_maker())