# CasinoAIBots API — Agent Integration Guide

> AI-powered house bots for online casino operators. Your coding agent configures tables, spawns bots, monitors performance, and tunes personas — all via API.
> Casino operators use coding agents (Claude Code, Cursor, Cline, etc.) to integrate CasinoAIBots into their platform. This doc is your agent's primary reference.

## Quick Reference — What Can My Agent Do?

| I want to... | Endpoint | Auth? |
|--------------|----------|-------|
| Check system health | GET /health | No |
| Get full session state | GET /api/session | API key |
| Configure a table | POST /api/tables/:tableId/configure | API key |
| Fill a table with bots | POST /api/tables/:tableId/fill | API key |
| Drain bots from a table | POST /api/tables/:tableId/drain | API key |
| Spawn a specific bot | POST /api/bots/spawn | API key |
| Remove a bot | DELETE /api/bots/:botId | API key |
| Request a bot decision | POST /api/decide | API key |
| Request bot chat | POST /api/chat | API key |
| Report opponent action | POST /api/observe | API key |
| Get opponent stats | GET /api/tables/:tableId/opponents | API key |
| List personas (base + your tuning) | GET /api/personas | API key |
| Tune a persona | PUT /api/personas/:type/overrides | API key |
| Reset persona tuning | DELETE /api/personas/:type/overrides | API key |
| Check usage & quota | GET /api/usage | API key |
| Get system stats | GET /api/stats | API key |
| Connect to casino platform | POST /api/bridge/connect | API key |
| Ask tauAI support | POST /api/support/message | No |

## Agent Signup (No Account? Start Here)

No API key yet? Self-provision instantly — no dashboard, no email required:

`POST /api/signup` with `{ "slug": "my-casino", "name": "My Casino", "email": "you@casino.com" }`

Returns: API key + payment URL. Key is gated until $1 verification (anti-spam).
Email is optional — if provided, you'll receive the $1 payment link. If not, use the paymentUrl in the response.

## Agent Session Pattern (START HERE)

On every session start, your agent should make ONE call to get the full picture:

`GET /api/session` → returns: health, active tables, bot counts, table configs, LLM stats, bridge connections, system stats — all in one response.

Then work. Only use individual endpoints (GET /api/tables/:id/bots, GET /api/stats) for targeted queries.

DO NOT loop through individual endpoints. The session call gives your agent everything it needs to understand current state.

## Authentication

Header: `Authorization: x-api-key YOUR_API_KEY`
Alternative: `?apiKey=YOUR_API_KEY` query parameter.
Get an API key via the operator dashboard at /dashboard.

## Core Concepts

### Games
- **Poker (Texas Hold'em)** — Seat-based, turn-by-turn. GTO-lite + pot odds + bluffing + opponent exploitation (steal vs tight, fold to rocks, call maniacs light, thin value vs fish — via poker.exploitSkill persona knob; feed /api/observe or supply opponents/aggressorId in gameState).
- **Blackjack** — Seat-based, per-round. Full basic strategy (hard/soft) + optional Hi-Lo card counting (bet spread + true-count deviations via blackjack.cardCounting persona knob; feed runningCount/decksRemaining or dealtCards in gameState).
- **Crash** — Bet-based, shared round. Gaussian auto-cashout distribution.

### Bot Capability Tiers (per-table setting, distinct from billing plan)
- **free (Basic Bots)** — Rules-based. Pot odds, basic strategy, auto-cashout.
- **pro (Smart Bots)** — Personas + opponent tracking + canned chat.
- **enterprise (AI Bots)** — LLM-powered + opponent modeling + dynamic chat. Requires Studio/Enterprise plan.

Billing plans (Starter/Pro/Studio/Enterprise) are usage-based — see Pricing below.

### Personas
5 configurable play styles: shark (tight-aggressive), fish (loose-passive), rock (ultra-tight), maniac (hyper-aggressive), beginner (random with mistakes).

### Humanizer
All bots include realistic behavior: gaussian delays (1.5-4s), bet variance (+-15%), configurable mistake rate.

## Table Configuration

POST /api/tables/:tableId/configure
```json
{
  "tier": "pro",
  "botCount": 4,
  "difficulty": "medium",
  "gameType": "poker",
  "personaMix": { "shark": 1, "fish": 2, "beginner": 1 }
}
```

Fields:
- tier: "free" | "pro" | "enterprise"
- botCount: number of bots (1-8)
- difficulty: "easy" | "medium" | "hard"
- gameType: "poker" | "blackjack" | "crash"
- personaMix: optional object mapping persona types to counts

GET /api/tables/:tableId/config → current configuration

## Spawning & Managing Bots

POST /api/tables/:tableId/fill → spawn bots per table config
POST /api/tables/:tableId/drain → remove all bots from table
POST /api/bots/spawn → spawn single bot:
```json
{
  "tableId": "table-123",
  "gameType": "poker",
  "persona": "shark",
  "tier": "pro"
}
```
DELETE /api/bots/:botId → remove specific bot
GET /api/tables/:tableId/bots → list bots at table

## Bot Decisions (for direct integration)

POST /api/decide → request bot decision:
```json
{
  "botId": "bot-abc",
  "gameType": "poker",
  "gameState": {
    "seatIndex": 2,
    "phase": "flop",
    "holeCards": ["As", "Kh"],
    "communityCards": ["Jd", "Ts", "3c"],
    "pot": 150,
    "currentBet": 50,
    "playerBet": 0,
    "playerChips": 500,
    "blinds": { "small": 5, "big": 10 }
  }
}
```
Returns: `{ "action": "raise", "amount": 100, "delay": 2300, "chat": "Let's play" }`

POST /api/chat → request bot chat message:
```json
{ "botId": "bot-abc", "gameType": "poker", "event": "win" }
```

## Opponent Modeling

POST /api/observe → report player action (bots learn from this):
```json
{
  "tableId": "table-123",
  "playerId": "human-456",
  "action": "raise",
  "amount": 100,
  "gameType": "poker",
  "context": { "phase": "preflop", "pot": 30 }
}
```

GET /api/tables/:tableId/opponents → opponent stats (VPIP, PFR, AF, classification)

## Persona Tuning (Per-Operator Overrides)

Tune any persona's play style — overrides apply to all bots you spawn (base personas unchanged for other operators).

GET /api/personas → all personas with base, your overrides, and effective (merged) config
GET /api/personas/:type/overrides → your overrides for one persona
PUT /api/personas/:type/overrides → set overrides (partial; validated & clamped):
```json
{
  "stats": { "vpip": [0.2, 0.3], "af": [2.5, 3.5], "bluffFreq": [0.1, 0.2], "mistakeRate": [0.01, 0.03] },
  "poker": { "betSizingPotFraction": [0.5, 0.8], "continuationBet": 0.7 },
  "blackjack": { "basicStrategyAdherence": 0.98 },
  "crash": { "cashoutMean": 2.5, "cashoutStddev": 0.8 },
  "humanizer": { "delayMean": 2000, "delayStddev": 800 },
  "names": ["Ace", "Lucky_Lu"]
}
```
DELETE /api/personas/:type/overrides → reset persona to defaults

Ranges are [min, max] arrays. Rates are 0–1. Delays in ms. Out-of-range values are clamped.

## Usage & Quota

GET /api/usage → your decision metering:
```json
{
  "tier": "pro", "decisionsThisMonth": 1234, "included": 50000,
  "remaining": 48766, "percentUsed": 2, "overageCount": 0,
  "overageRate": 0.003, "overageCost": 0, "hardCap": false,
  "monthResetAt": "...", "daily": [{"date": "2026-05-20", "count": 42}],
  "byGame": {"poker": 1000}, "byTable": {"poker-1": 1000}
}
```

Starter is hard-capped: POST /api/decide returns **429** with an upgrade hint once 5,000 decisions are used. Paid tiers continue with per-decision overage billing. Quotas reset monthly on renewal.

## Socket.IO Bridge (Real-Time Integration)

POST /api/bridge/connect → connect bots to external casino platform:
```json
{
  "platformUrl": "wss://your-casino.com",
  "namespace": "/game",
  "tableId": "table-123"
}
```

Bots connect via Socket.IO using the same protocol as human players. Events:
- Poker: poker:state, poker:action, poker:chat
- Blackjack: blackjack:yourTurn, blackjack:action, blackjack:chat
- Crash: crash:tick, crash:bet, crash:cashout, crash:chat

POST /api/bridge/disconnect → disconnect bridge
GET /api/bridge/status → connection status

## System Stats

GET /api/stats → full system statistics:
- Active bots, tables, tier distribution
- LLM usage (calls, tokens, cost estimate)
- Decision counts by game type
- Opponent models tracked

GET /api/session → everything above + health + configs in one call

## tauAI Support (No Auth Required)

POST /api/support/message → ask tauAI anything:
```json
{ "message": "How do I configure poker bots?", "sessionId": "agent-session-1" }
```
Returns AI-powered answer routed through h-conductor domain experts.

GET /api/support/history?sessionId=xxx → conversation history

## Integration Patterns for Agents

### Pattern 1: Table Auto-Fill (Most Common)
1. GET /api/session → check current state
2. POST /api/tables/poker-1/configure → set tier, bot count, personas
3. POST /api/tables/poker-1/fill → bots join automatically
4. Monitor: GET /api/stats → track performance

### Pattern 2: Direct Decision Integration
1. POST /api/bots/spawn → create bot with persona
2. On each game state update: POST /api/decide → get bot action
3. Report opponent actions: POST /api/observe → bots learn
4. Bot adapts play over time based on opponent models

### Pattern 3: Full Platform Bridge
1. POST /api/bridge/connect → connect to your casino Socket.IO
2. POST /api/tables/poker-1/configure → configure bots
3. POST /api/tables/poker-1/fill → bots auto-join via Socket.IO
4. Bots play autonomously — indistinguishable from human players

## Pricing (Usage-Based)

1 decision = 1 bot action (fold, call, raise, hit, stand, cashout).

| Tier | Price | Included Decisions | Overage | Tables |
|------|-------|-------------------|---------|--------|
| Starter | $1 one-time | 5,000/mo (hard cap) | None | 3 |
| Pro | $49/mo | 50,000/mo | $0.003/decision | 25 |
| Studio | $149/mo | 200,000/mo | $0.002/decision | 100 |
| Enterprise | $499/mo | 1,000,000/mo | $0.0015/decision | Unlimited |

## Key Patterns
- Table IDs: any string identifier from your platform
- Bot IDs: auto-generated (returned on spawn)
- Persona types: "shark", "fish", "rock", "maniac", "beginner"
- Game types: "poker", "blackjack", "crash"
- Tiers: "free", "pro", "enterprise"
- Difficulty: "easy", "medium", "hard"

## CLI & MCP (cab-cli)

Agent-first CLI mirroring this API — `cab` (npm: cab-cli):
- `cab signup --slug my-casino` → self-provision API key
- `cab login --key KEY` · `cab status` (one-call session) · `cab usage`
- `cab table configure T --tier pro --bots 4 --game poker --mix shark:1,fish:2` · `cab table fill|drain T`
- `cab bot spawn --table T --game poker --persona shark` · `cab bots`
- `cab decide --bot ID --game poker --state '{...}'` · `cab observe` · `cab chat`
- `cab persona tune shark --set poker.exploitSkill=0.9` · `cab opponents T` · `cab bridge connect`
- `cab skill [poker|blackjack|crash]` → print agent skill docs
- `cab mcp-serve` → MCP server (stdio JSON-RPC) with 22 cab_* tools for Claude Code

## Full Documentation

- [Agent Skill File](/api/docs/skill.md) — Add to your CLAUDE.md / .cursorrules
- [Poker Skill](/api/docs/skills/poker.md) — full Texas Hold'em integration pattern (decide loop, gameState schema, opponent modeling)
- [Blackjack Skill](/api/docs/skills/blackjack.md) — bet + play decisions, basic strategy knobs
- [Crash Skill](/api/docs/skills/crash.md) — bet + gaussian auto-cashout pattern
- [Quickstart Guides](/docs/quickstart) — Per-agent setup guides
- [Dashboard](/dashboard) — Operator management UI
- [Health](/health) — System status