# 🎲 rollhub-dice

[![PyPI version](https://img.shields.io/pypi/v/rollhub-dice)](https://pypi.org/project/rollhub-dice/)
[![Python](https://img.shields.io/pypi/pyversions/rollhub-dice)](https://pypi.org/project/rollhub-dice/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Python SDK for the **Rollhub Dice Agent API** — provably fair dice betting for AI agents.

## Quick Start

```bash
pip install rollhub-dice
```

```python
from rollhub_dice import DiceAgent

agent = DiceAgent(api_key="rh_sk_...")
result = agent.bet(target=0.5, direction="over", amount=100)
print(result)  # Bet #1: rolled 0.7234 → WIN (payout: 198)
```

## Register a New Agent

```python
agent = DiceAgent.register(wallet_address="0xYourWallet...")
print(agent.api_key)  # rh_sk_...
```

## API Reference

### `DiceAgent(api_key, base_url="https://agent.rollhub.com/api/v1")`

Create a client with an existing API key. Use `base_url` to point at staging:

```python
agent = DiceAgent(api_key="rh_sk_...", base_url="https://agent.rollhub.com/api/v1")
```

### `DiceAgent.register(wallet_address, base_url) → DiceAgent`

Register a new agent wallet and return an authenticated client.

### `agent.balance() → Balance`

```python
bal = agent.balance()
print(bal.balance_usd)   # "10.00"
print(bal.balance_cents)  # 1000
```

### `agent.bet(target, direction, amount, client_secret) → BetResult`

Place a dice bet. Amount is in **cents**.

| Param | Default | Description |
|-------|---------|-------------|
| `target` | — | Threshold (0.0–1.0) |
| `direction` | `"over"` | `"over"` or `"under"` |
| `amount` | `100` | Wager in cents |
| `client_secret` | *auto* | Your secret for verification |

```python
result = agent.bet(target=0.5, direction="over", amount=200)
print(result.win, result.roll, result.payout)
```

### `agent.bets() → List[Bet]`

Get your bet history.

### `agent.verify(bet_id) → VerifyResult`

Verify any bet was provably fair:

```python
v = agent.verify(bet_id=1)
print(v.verified)  # True
```

## Provably Fair

Every bet is verifiable using **SHA3-384 HMAC**:

1. Before you bet, Rollhub publishes `server_seed_hash = SHA3-384(server_secret)`
2. You provide a `client_secret` (auto-generated if omitted)
3. Roll = first 8 bytes of `HMAC-SHA3-384(server_secret, client_secret:nonce)` → `[0, 1)`
4. After the bet, the `server_secret` is revealed so you can recompute the roll

You can also verify locally:

```python
from rollhub_dice import verify_bet

is_fair = verify_bet(
    server_secret="...",
    client_secret="...",
    nonce=1,
    server_seed_hash="...",
    expected_roll=0.7234,
)
```

## Error Handling

```python
from rollhub_dice import DiceAgent, AuthenticationError, InsufficientBalanceError

try:
    result = agent.bet(target=0.5, amount=100)
except AuthenticationError:
    print("Bad API key")
except InsufficientBalanceError:
    print("Need more funds")
```

All exceptions inherit from `RollhubError` and include `status_code` and `response` attributes.

## Docs

Full documentation: [rollhub.com/docs](https://rollhub.com/docs)

## License

MIT
