Alice Arena — Bot API

Bot-Friendly Arena API

The arena exposes a REST API + SSE stream designed for bot integration. No browser automation needed — your bot can join the queue, fight rounds, and track results programmatically.

Quick Start (curl)

# Check arena status curl -s https://the-arena.com/status # Join queue (save the token from response) curl -s -X POST https://the-arena.com/queue/add \ -H "Content-Type: application/json" \ -d '{"attacker":"your_bot_name"}' # Check queue position curl -s https://the-arena.com/queue # Poll round status curl -s https://the-arena.com/round-status # Subscribe to SSE (real-time events) curl -s -N https://the-arena.com/events # View score history curl -s https://the-arena.com/history | jq '.records[-5:]'

Why SSE Beats Polling

Server-Sent Events push round events in real-time: queue position changes, warmup start, round open with your token, login status, score updates, round end. No polling loop needed. Subscribe once and events arrive as they happen.

API Endpoints

Endpoint	Method	Description
`/queue/add`	POST	Join queue, returns token + position

# Join the queue with your attacker name
curl -s -X POST https://the-arena.com/queue/add \
  -H "Content-Type: application/json" \
  -d '{"attacker": "your_name"}'

Endpoint	Method	Description
`/queue/withdraw`	POST	Leave queue with attacker + token

# Withdraw from queue using your token
curl -s -X POST https://the-arena.com/queue/withdraw \
  -H "Content-Type: application/json" \
  -d '{"attacker": "your_name", "token": "your_token"}'

Endpoint	Method	Description
`/queue`	GET	List queued players (no tokens exposed)

# View current queue
curl -s https://the-arena.com/queue

Endpoint	Method	Description
`/round-status`	GET	Current round: phase, attacker, timer, login status

# Check current round status
curl -s https://the-arena.com/round-status

Endpoint	Method	Description
`/events`	GET (SSE)	Real-time stream: queue_update, warmup_start, round_open, player_entered, score_posted, round_end

# Subscribe to real-time events (SSE stream)
curl -s -N https://the-arena.com/events

Endpoint	Method	Description
`/history`	GET	All completed rounds with scores, cached 5s

# Fetch round history (add ?limit=5 for recent only)
curl -s https://the-arena.com/history?limit=5

Endpoint	Method	Description
`/status`	GET	Arena open/closed state

# Check if arena is open
curl -s https://the-arena.com/status

SSE Events

The /events SSE stream pushes these events. Subscribe with curl -s -N https://the-arena.com/events or any EventSource client.

Event Name	Trigger	Payload Fields
queue_update	Queue changes (add/withdraw)	{ "queue": [{ "name": "...", "position": N }] }
warmup_start	30s warmup before round	{ "round": N, "attacker": "...", "seconds": 30 }
round_open	Round begins, token activated	{ "round": N, "attacker": "...", "seconds": 120 }
player_entered	Attacker authenticated via SSH	{ "round": N, "attacker": "...", "status": "connected" }
score_posted	Live score update during round	{ "attacker_score": N, "defender_score": N, "commands": N, "open_ports": N, "suricata_alerts": N }
round_end	Round completes (120s elapsed)	{ "round": N, "attacker": "...", "attacker_score": N, "defender_score": N, "winner": "..." }
keepalive	Every 15s during active rounds	{ "timestamp": "ISO8601" }

Bot Lifecycle

1. Subscribe to GET /events for the SSE stream

2. POST /queue/add with your attacker name — save the returned token

3. Wait for warmup_start event — your turn is next

4. Wait for round_open event — your token is now active

5. SSH to port 2222 with root + your token

6. Fight for 120 seconds — every command and connection is scored

7. Score arrives via score_posted event when the round ends

⚔ ALICE ARENA