Data Models

Typed Pydantic models for every object returned by the Stake.com API.

Overview

All models are built with Pydantic v2 and provide full type safety. Every model exposes a from_dict() classmethod to construct instances from raw API response dictionaries. Fields use Python-native types — Decimal for monetary values, datetime for timestamps, Optional[T] where the API may omit a field.

Import:

from stakeapi.models import User, Game, SportEvent, Bet, Transaction, Statistics

Class: User

Represents a Stake.com user account.

Fields

from_dict(data) (classmethod)

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "User"

Construct a User from a raw dictionary (e.g. from a GraphQL response).

Example

from stakeapi.models import User
from datetime import datetime, timezone

user = User(
    id="u_12345",
    username="highroller",
    email="player@example.com",
    verified=True,
    created_at=datetime(2023, 6, 1, tzinfo=timezone.utc),
    country="US",
    currency="USD",
)

print(user.username)       # highroller
print(user.verified)       # True
print(user.created_at)     # 2023-06-01 00:00:00+00:00

Usage with StakeAPI

async with StakeAPI(access_token="...", cf_clearance="...") as client:
    user = await client.get_user_profile()
    print(f"{user.username} ({user.country})")
    if not user.verified:
        print("Account not verified — some features may be restricted.")

Class: Game

Represents a casino game available on Stake.com.

Fields

from_dict(data) (classmethod)

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Game"

Example

from stakeapi.models import Game
from decimal import Decimal

game = Game(
    id="plinko",
    name="Plinko",
    category="originals",
    provider="Stake Originals",
    min_bet=Decimal("0.00000001"),
    max_bet=Decimal("100.00"),
    rtp=97.0,
    volatility="high",
    features=["multiplier"],
)

print(f"{game.name} — RTP: {game.rtp}%")
print(f"Bets: {game.min_bet} to {game.max_bet}")

Usage with StakeAPI

async with StakeAPI(access_token="...", cf_clearance="...") as client:
    games = await client.get_casino_games(category="originals")
    with_rtp = [g for g in games if g.rtp is not None]
    with_rtp.sort(key=lambda g: g.rtp, reverse=True)
    print("Top 5 highest RTP Originals:")
    for g in with_rtp[:5]:
        print(f"  {g.name}: {g.rtp}%")

Class: SportEvent

Represents a live or upcoming sports betting event.

Fields

from_dict(data) (classmethod)

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "SportEvent"

Example

from stakeapi.models import SportEvent
from datetime import datetime, timezone

event = SportEvent(
    id="evt_789",
    sport="Football",
    league="Premier League",
    home_team="Arsenal",
    away_team="Chelsea",
    start_time=datetime(2025, 9, 15, 20, 0, tzinfo=timezone.utc),
    status="scheduled",
    odds={"home": 1.85, "draw": 3.50, "away": 4.20},
    live=False,
)

print(f"{event.home_team} vs {event.away_team}")
print(f"Kick-off: {event.start_time}")
print(f"Home win odds: {event.odds.get('home', 'N/A')}")

Usage with StakeAPI

async with StakeAPI(access_token="...", cf_clearance="...") as client:
    events = await client.get_sports_events(sport="football")
    live_events = [e for e in events if e.live]
    print(f"Live matches: {len(live_events)}")
    for event in live_events:
        best = max(event.odds.values()) if event.odds else "N/A"
        print(f"  {event.home_team} vs {event.away_team} — best odds: {best}")

Class: Bet

Represents a placed bet on a casino game or sports event.

Fields

from_dict(data) (classmethod)

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Bet"

Example

from stakeapi.models import Bet
from decimal import Decimal
from datetime import datetime, timezone

bet = Bet(
    id="bet_abc",
    user_id="u_12345",
    game_id="dice",
    bet_type="casino",
    amount=Decimal("0.00001"),
    potential_payout=Decimal("0.00002"),
    status="won",
    placed_at=datetime(2025, 1, 10, 14, 30, tzinfo=timezone.utc),
)

profit = bet.potential_payout - bet.amount if bet.status == "won" else -bet.amount
print(f"Bet: {bet.amount} → {bet.status} (P&L: {profit:+.8f})")

Usage with StakeAPI

async with StakeAPI(access_token="...", cf_clearance="...") as client:
    bets = await client.get_bet_history(limit=50)
    total_wagered = sum(b.amount for b in bets)
    total_won     = sum(b.potential_payout for b in bets if b.status == "won")
    print(f"Net: {total_won - total_wagered:+.8f}")

Class: Transaction

Represents a financial transaction: deposit, withdrawal, bet deduction, or win credit.

Fields

from_dict(data) (classmethod)

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Transaction"

Example

from stakeapi.models import Transaction
from decimal import Decimal
from datetime import datetime, timezone

tx = Transaction(
    id="tx_001",
    user_id="u_12345",
    type="deposit",
    amount=Decimal("0.01"),
    currency="btc",
    status="completed",
    timestamp=datetime(2025, 3, 1, 10, 0, tzinfo=timezone.utc),
    description="Bitcoin deposit",
)

print(f"{tx.type.capitalize()}: {tx.amount} {tx.currency.upper()} ({tx.status})")

Class: Statistics

Aggregated betting statistics for a user account.

Fields

from_dict(data) (classmethod)

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Statistics"

Example

from stakeapi.models import Statistics
from decimal import Decimal

stats = Statistics(
    total_bets=1500,
    total_wagered=Decimal("0.15"),
    total_won=Decimal("0.14"),
    total_lost=Decimal("0.01"),
    win_rate=48.7,
    biggest_win=Decimal("0.005"),
    favorite_game="dice",
)

print(f"Bets:      {stats.total_bets}")
print(f"Win rate:  {stats.win_rate:.1f}%")
print(f"Net P&L:   {stats.total_won - stats.total_wagered:+.8f}")
print(f"Best win:  {stats.biggest_win:.8f}")

Model Summary

See Also

• StakeAPI Client — Methods that return these models
• Endpoints — GraphQL queries that power the data
• Utilities — safe_decimal(), format_currency(), and helpers
• Exceptions — Error types you may encounter