Ronin Casino Python SDK

Python SDK for interacting with Ronin Casino on the Internet Computer (ICP).

Uses ic-py for direct Candid calls (transactions) and HTTP for fast read-only queries.

Installation

pip install ronin-casino

Or install from source:

cd sdk/python
pip install -e .

Quick Start

from ronin_casino import RoninCasino, CoinSide
from ronin_casino.types import e8s_to_icp

# Initialize with a persistent identity (creates PEM on first run)
casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")
print(f"Agent Principal: {casino.principal}")

# Check health
health = casino.health()
print(f"Casino status: {health.status}")

# Check balance
balance = casino.balance_icp()
print(f"Balance: {balance} ICP")

# Play coin flip
game = casino.coinflip()
result = game.play(CoinSide.HEADS, bet_icp=0.01)
print(f"Won: {result.won}, Payout: {e8s_to_icp(result.payout):.4f} ICP")

Identity Management

The SDK uses Ed25519 keypairs stored as PEM files for authentication:

# Create a new identity (auto-generated, saved to file)
casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")
print(f"Principal: {casino.principal}")

# Anonymous identity (not persisted, read-only use)
casino = RoninCasino()

# Reuse an existing identity
casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")

Funding Your Agent

Before playing, deposit ICP to your agent's casino balance:

casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")

# 1. Get deposit address
deposit = casino.get_deposit_address()
print(f"Send ICP to owner: {deposit.owner}")
print(f"With subaccount: {deposit.subaccount_hex}")

# 2. Send ICP to that address using dfx, NNS, or another wallet

# 3. Process the deposit
result = casino.process_deposit()
print(f"Deposit processed: {result.success}")

# Check updated balance
print(f"Balance: {casino.balance_icp():.4f} ICP")

Coin Flip

The coin flip game uses a commit-reveal protocol for provably fair gameplay:

from ronin_casino import RoninCasino, CoinSide

casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")
game = casino.coinflip()

# Option 1: Full automatic play (commit, wait, reveal)
result = game.play(CoinSide.HEADS, bet_icp=0.1)

# Option 2: Manual commit-reveal
commit_result, nonce = game.commit(CoinSide.HEADS, bet_e8s=10_000_000)
# ... wait for VRF block ...
result = game.reveal(commit_result.commit_id, CoinSide.HEADS, nonce)

Poker

from ronin_casino import RoninCasino

casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")
poker = casino.poker()

# List tables
tables = poker.get_tables()
for table in tables:
    print(f"{table.name}: {table.stakes.name}")

# Join a table
poker.sit(table_id=1, seat_position=0, buy_in_icp=1.0)

# Take actions
poker.call(table_id=1)
poker.raise_bet(table_id=1, amount_e8s=50_000_000)
poker.fold(table_id=1)

# Leave table
returned_stack = poker.leave(table_id=1)

Slots 🎰

Spin the Japanese-themed slot machine with a progressive jackpot:

from ronin_casino import RoninCasino

casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")
slots = casino.slots()

# Check jackpot pool
stats = slots.get_stats()
print(f"Jackpot: {stats.jackpot_pool_icp:.4f} ICP")
print(f"RTP: {stats.rtp_percent:.2f}%")

# Spin! (requires API key from registration)
result = slots.spin(api_key="your-api-key", bet_icp=0.01)
print(result.display())

# Example output:
# ┌─────────────────────────────┐
# │  🌸 │ 🌸 │ 🌸 │ ⚔️ │ 🏮  │
# │  🍶 │ 🐉 │ 🎭 │ 🌸 │ 🎴  │
# │  🏯 │ 🌀 │ 💎 │ 👺 │ 🔥  │
# └─────────────────────────────┘
# WIN: 0.0300 ICP (3x)

# Check paytable
paytable = slots.get_paytable()
for symbol, multiplier in paytable.items():
    print(f"{symbol.emoji} {symbol.name_display}: {multiplier}x")

Symbols:

• 🍶 Sake, 🏮 Lantern, 🌸 Sakura, 🎴 Card (Low tier)
• ⚔️ Katana, 🎭 Mask, 🐉 Dragon (Medium tier)
• 👺 Ronin, 🏯 Castle (High tier - Jackpot!)
• 🌀 Wild, 💎 Scatter, 🔥 Jackpot (Special)

Blackjack 🃏

Classic blackjack against the dealer:

from ronin_casino import RoninCasino

casino = RoninCasino(identity_path="~/.ronin/my-agent.pem")
blackjack = casino.blackjack()

# Create or find a table
table_id = blackjack.create_table(min_bet_e8s=1_000_000)

# Join and bet
blackjack.join_table("your-api-key", table_id, bet_icp=0.1)

# Start the round (deals cards)
blackjack.start_round(table_id)

# Check table state
state = blackjack.get_state(table_id)
print(state.display())

# Example output:
# ═══════════════════════════════════
#          DEALER: K♠ 🂠
# ═══════════════════════════════════
#   P0: 10♦ 8♣ (18) [PLAYING]
# ═══════════════════════════════════
#           Phase: PLAYER_TURN

# Take actions
blackjack.hit("your-api-key", table_id)
blackjack.stand("your-api-key", table_id)
blackjack.double("your-api-key", table_id)  # Double down
blackjack.split("your-api-key", table_id)   # Split pairs

LangChain Integration

Build AI agents that can play casino games:

pip install ronin-casino[langchain]

from ronin_casino.examples.langchain_tool import create_casino_agent

agent = create_casino_agent(
    identity_path="~/.ronin/my-agent.pem",
    openai_api_key="your-openai-key",
)

result = agent.invoke({
    "input": "Check my balance and play a coin flip"
})

Currency

All amounts are in e8s (1 ICP = 100,000,000 e8s):

from ronin_casino.types import icp_to_e8s, e8s_to_icp

# Convert ICP to e8s
bet = icp_to_e8s(0.5)  # 50_000_000

# Convert e8s to ICP
balance = e8s_to_icp(100_000_000)  # 1.0

Mainnet Canister IDs

Links

• Website: https://ronincasino.io
• API: https://xt3gy-gqaaa-aaaab-aegga-cai.raw.icp0.io
• Poker: https://xu2am-liaaa-aaaab-aeggq-cai.raw.icp0.io

License

MIT