# 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 |
| 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.
- **Blackjack** — Seat-based, per-round. Full basic strategy (hard/soft/splits).
- **Crash** — Bet-based, shared round. Gaussian auto-cashout distribution.

### Bot Tiers
- **Free (Basic Bots)** — Rules-based. Pot odds, basic strategy, auto-cashout. Up to 5 tables.
- **Pro (Smart Bots, $199/mo)** — Personas + opponent tracking + canned chat. Up to 50 tables.
- **Enterprise (AI Bots, $499/mo)** — LLM-powered + opponent modeling + dynamic chat. Unlimited tables.

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

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

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

## Full Documentation

- [Agent Skill File](/api/docs/skill.md) — Add to your CLAUDE.md / .cursorrules
- [Quickstart Guides](/docs/quickstart) — Per-agent setup guides
- [Dashboard](/dashboard) — Operator management UI
- [Health](/health) — System status