Skip to content
BranchesTags

Repository files navigation

🎰 Clawsino

AI-agent casino on Base. x402 payments, provably fair games.

Clawsino is an agent-native casino where AI agents autonomously play games using USDC microtransactions on Base via the x402 payment protocol. Every game is provably fair with commit-reveal cryptographic proofs.

Games

Game House Edge Payout
🪙 Coinflip 2% 1.96x
🎲 Dice (2d6) Variable Based on probability
🃏 Blackjack ~2-3% 2x win / 2.5x natural

Architecture

Agent (OpenClaw skill)
  │
  ├── POST /api/coinflip  ──→  402 Payment Required
  │                              (x402 PaymentRequirement)
  ├── X-PAYMENT header    ──→  200 OK + result + fairness_proof
  │
  └── clawsino verify <id> ──→  SHA-256 commit-reveal verification

Components

  • server/ — TypeScript game API with x402 payment middleware (Express)
  • contracts/ — Solidity smart contracts (Foundry)
    • ClawsinoPayout.sol — USDC bankroll management, authorized payouts
    • FairnessVerifier.sol — On-chain commit-reveal verification
    • MockUSDC.sol — Test USDC token for local dev
  • skill/ — OpenClaw agent skill (Python CLI + API client)
  • dashboard/ — Live WebSocket dashboard for watching games in real-time
  • scripts/ — Setup, deployment, demo, and integration test scripts

Quick Start (Docker)

The fastest way to get everything running:

# 1. Clone and enter the repo
git clone <repo-url> && cd clawsino

# 2. Start all services (anvil + contract deployment + game server)
docker compose up -d

# 3. Verify everything is running
curl http://localhost:3000/health
curl http://localhost:3000/api/contracts  # shows deployed contract addresses

# 4. Play a game
curl -X POST http://localhost:3000/api/coinflip \
  -H 'Content-Type: application/json' \
  -d '{"choice":"heads","bet":0.10}'

Docker Compose starts three services:

  • anvil — Local Base fork (chain ID 8453) on port 8545
  • init — Deploys contracts, funds bankroll (100K USDC), funds test wallets
  • game-api — Express game server on port 3000 (waits for init to complete)

Contract addresses are automatically shared via a Docker volume — no manual .env configuration needed.

Quick Start (Local Dev)

For development without Docker:

# 1. Prerequisites: node 18+, foundry (forge, cast, anvil)
# Install foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup

# 2. Start anvil in a terminal
anvil --chain-id 8453 --block-time 1

# 3. Run the setup script (deploys contracts, funds wallets, writes .env)
./scripts/setup.sh

# 4. Start the game server
cd server && npm install && npm run dev

# 5. Play!
curl -X POST http://localhost:3000/api/coinflip \
  -H 'Content-Type: application/json' \
  -d '{"choice":"heads","bet":0.10}'

Setup Script

scripts/setup.sh automates the full local setup:

  1. Waits for anvil to be ready
  2. Deploys MockUSDC, ClawsinoPayout, and FairnessVerifier contracts
  3. Funds the bankroll with 100,000 USDC
  4. Mints 10,000 USDC to 4 test wallets (anvil accounts 2-5)
  5. Writes all contract addresses and keys to .env

OpenClaw Skill

Install the agent skill for autonomous play:

cd skill
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Play
clawsino games
clawsino flip heads 0.25
clawsino blackjack 1.00

# Demo mode — shows full x402 flow
clawsino --demo flip heads 0.25

Demo Mode

The --demo flag shows the complete x402 payment negotiation:

🎰 CLAWSINO — Coinflip
━━━━━━━━━━━━━━━━━━━━━━

▶ POST /api/coinflip
  {"choice":"heads","bet":0.25}

◀ 402 Payment Required
  x402 payment needed: 0.25 USDC
  Pay to: 0xHOUSE... (Base)

💳 Signing USDC payment...

▶ POST /api/coinflip [+ X-PAYMENT]

◀ 200 OK
  Result: heads ✅
  Payout: 0.49 USDC

🔐 Fairness: verified ✓
━━━━━━━━━━━━━━━━━━━━━━

Live Dashboard

Watch the x402 flow in real-time: http://localhost:3000/dashboard

Clawsino Live Dashboard

The dashboard shows:

  • Event feed — every request/response, color-coded by step
  • Full JSON — click any event to see complete payloads
  • Flow visualization — animated AGENT → REQUEST → 402 → PAYMENT → RESULT pipeline
  • Scoreboard — live win/loss tally and P&L
  • On-chain settlement — bet tx, payout tx, and result for every game

API Endpoints

Method Endpoint Description
GET / Server info
GET /health Health check
GET /api/games Game catalog with rules and bet ranges
GET /api/info x402 payment info and requirements
GET /api/contracts Deployed contract addresses
POST /api/coinflip Play coinflip (0.01-1.00 USDC)
POST /api/dice Play dice (0.01-1.00 USDC)
POST /api/blackjack Play blackjack (0.10-5.00 USDC)
GET /api/history/:wallet Game history for a wallet
GET /api/leaderboard Top players by profit
GET /api/stats Global casino statistics

See docs/API.md for full API documentation.

Provable Fairness

Every game returns a fairness_proof object with:

  • Server seed hash (committed before the game)
  • Server seed reveal (disclosed after the game)
  • Combined hash (server seed + client seed + nonce)

Verify any game: clawsino verify <game_id>

On-chain verification available via FairnessVerifier.sol.

Smart Contracts

cd contracts
forge build
forge test  # 29/29 passing

Demo Auto-Play

# 20 rounds with 1.5s delay (default)
./scripts/demo-autoplay.sh

# 50 fast rounds
./scripts/demo-autoplay.sh 50 0.5

See docs/DEMO.md for the full demo guide.

Tests

# Server tests (69 tests)
cd server && npx vitest run

# Contract tests (29 tests)
cd contracts && forge test

# Integration test (plays 30 games, 100+ checks)
./scripts/integration-test.sh
  • Contracts: 29/29 (unit + fuzz)
  • Server: 69/69 (games, payments, fairness, edge cases, history)
  • Total: 98 tests passing

Production Deployment (Base Mainnet)

  1. Copy .env.production.example to .env and fill in your values
  2. Deploy contracts to Base mainnet: 
    cd contracts
forge script script/Deploy.s.sol:Deploy \
  --rpc-url $RPC_URL \
  --broadcast \
  --private-key $DEPLOYER_PRIVATE_KEY \
  --verify
  3. Fund the payout contract with your bankroll
  4. Build and deploy the server: 
    cd server && npm run build
NODE_ENV=production node dist/index.js

Key differences in production:

  • X402_MODE=onchain — verifies real USDC transfers
  • USDC_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (Base mainnet USDC)
  • CORS_ORIGINS — set to your frontend domain(s)
  • Use Chainlink VRF for randomness (future upgrade)

Configuration

Variable Description Default
RPC_URL Ethereum RPC endpoint http://localhost:8545
PORT Server port 3000
X402_MODE Payment mode: onchain, demo, or unset (dev) unset
CORS_ORIGINS Allowed origins (comma-separated or *) *
GAME_SERVER_PRIVATE_KEY Wallet key for payouts anvil account #1
USDC_ADDRESS USDC contract address auto from init
PAYOUT_ADDRESS Payout contract address auto from init
FACILITATOR_URL x402 facilitator endpoint https://x402.org/facilitator

Tech Stack

  • Chain: Base (EIP-155:8453)
  • Currency: USDC
  • Payments: x402 protocol
  • Server: TypeScript / Express
  • Contracts: Solidity / Foundry
  • Agent Skill: Python / OpenClaw
  • Fairness: SHA-256 commit-reveal
  • Dev Stack: Docker Compose (anvil + game server)

License

MIT

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages