rollhub-dice 0.3.0

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

🎲 rollhub-dice

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

Quick Start

pip install rollhub-dice

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

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:

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

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

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:

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:

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

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

License

MIT