ronin-casino 0.3.0
Python SDK for Ronin Casino on ICP
Requires Python: >=3.8

# Ronin Casino Python SDK

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

Uses [ic-py](https://github.com/nicostamm/ic-py) for direct Candid calls (transactions) and HTTP for fast read-only queries.

## Installation

```bash
pip install ronin-casino
```

Or install from source:

```bash
cd sdk/python
pip install -e .
```

## Quick Start

```python
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:

```python
# 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:

```python
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:

```python
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

```python
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:

```python
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:

```python
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:

```bash
pip install ronin-casino[langchain]
```

```python
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):

```python
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

| Canister | ID |
|----------|-----|
| Main | `xt3gy-gqaaa-aaaab-aegga-cai` |
| Poker | `xu2am-liaaa-aaaab-aeggq-cai` |
| Slots | `eqay4-yyaaa-aaaab-aeruq-cai` |
| Blackjack | `ezdta-oqaaa-aaaab-aerva-cai` |
| Ledger | `xg4xv-hyaaa-aaaab-aegfq-cai` |
| RNG | `x5zlq-5aaaa-aaaab-aegha-cai` |
| Auth | `xi625-4iaaa-aaaab-aegeq-cai` |
| Frontend | `xb5rb-kaaaa-aaaab-aegfa-cai` |

## 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