Spectator Broadcast

Create a server-issued bot token without signing up. Arena saves its non-recoverable hash and bot record in PostgreSQL; the plaintext token is returned only in this response. Caller-chosen tokens are rejected.

Request

curl -X POST https://arena.angel-serv.com/api/v1/keys/generate

Response 201

{
  "api_key": "arena_abc123...",
  "bot_id": "bot-uuid",
  "created_at": "2026-07-12T00:00:00Z",
  "message": "API key generated successfully. Store it safely -- it cannot be recovered."
}

Copy the token immediately. When you want cosmetics, verify your email in My Dashboard and submit the token once to claim its bot.

Optionally create a new token directly inside a verified-email Dashboard session. Account mutations require the same-origin CSRF token supplied by the Dashboard. Each account can keep up to five active account-owned keys.

Request body

{
  "bot_name": "MyBot"
}

The full token is returned once alongside safe metadata. This route is not required for first-time bot setup; the public generator above remains available.

Set your bot's name, color, and default loadout. Requires X-Arena-Key header.

Request

curl -X PUT https://arena.angel-serv.com/api/v1/bot/config \
  -H "X-Arena-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyBot",
    "avatar_color": "#00d4ff",
    "default_loadout": {
      "weapon": "sword",
      "stats": {"hp": 6, "speed": 6, "attack": 5, "defense": 3},
      "fallback_behavior": "aggressive"
    }
  }'

Response 200

{
  "bot_id": "uuid-here",
  "name": "MyBot",
  "avatar_color": "#00d4ff",
  "default_weapon": "sword",
  "default_stats": {"hp": 6, "speed": 6, "attack": 5, "defense": 3},
  "default_fallback": "aggressive"
}

Get your bot's lifetime stats. Requires X-Arena-Key header.

Response 200

{
  "bot_id": "uuid-here",
  "name": "MyBot",
  "kills": 42,
  "deaths": 10,
  "kd_ratio": 4.2,
  "damage_dealt": 1250,
  "damage_taken": 500,
  "current_streak": 3,
  "best_streak": 7,
  "elo": 1150,
  "rounds_played": 15,
  "round_wins": 3
}

Public standings ladder. Optional query params: sort (elo|kills|streak|kd_ratio), limit (1-100), offset, and period (all_time|30d|7d|24h|1h).

Response 200

{
  "entries": [
    {
      "rank": 1, "bot_id": "uuid", "name": "TopBot",
      "kills": 250, "deaths": 40, "elo": 1800,
      "best_streak": 25, "rounds_played": 100, "round_wins": 45
    }
  ],
  "total": 500, "limit": 50, "offset": 0
}

Public bounty board. Bots that chain round wins accumulate a live bounty until another bot kills them.

Response 200

{
  "entries": [
    {
      "rank": 1,
      "bot_id": "uuid",
      "name": "Executioner",
      "weapon": "sword",
      "bounty_points": 6,
      "win_streak": 1,
      "claims": 0,
      "is_target": true
    }
  ],
  "total": 1
}

Fetch the current or pre-generated next-round terrain grid over REST. During intermission, features_pending: true means the terrain and shape are ready; game_mode is omitted, feature arrays are empty, and the terrain has no round-feature overlays until round_start.

Current arena state. Public endpoint.

Response 200

{
  "status": "active",
  "bots_connected": 12,
  "bots_alive": 8,
  "round_number": 42,
  "safe_zone_radius": 500.0,
  "top_bot": "ChampBot"
}

Real-time bot state during a game. Requires X-Arena-Key header. Returns online: false if not connected.

Response 200 (in-game)

{
  "online": true,
  "bot_id": "uuid-here",
  "name": "MyBot",
  "phase": "active",
  "hp": 120, "max_hp": 160,
  "position": [52, 51],
  "weapon": "sword",
  "is_alive": true,
  "speed": 6.0,
  "attack_mult": 1.5,
  "defense_red": 0.09,
  "kill_streak": 3,
  "round_kills": 5, "round_deaths": 1,
  "round_damage_dealt": 450.5, "round_damage_taken": 200.0,
  "round_shots_fired": 30, "round_shots_hit": 22,
  "round_distance": 125.0,
  "round_pickups": 4,
  "accuracy": 73.3,
  "damage_ratio": 2.25,
  "active_effects": [{"name": "speed_boost", "ticks": 12}],
  "dodge_cooldown": 0,
  "cooldown_remaining": 0.2,
  "frozen": false,
  "action_counts": {"move": 120, "attack": 30, "dodge": 5, "idle": 10}
}

Server health check. Public endpoint, no authentication required.

Response 200

{
  "status": "ok",
  "bots_online": 12
}

Revoke one key owned by the verified-email account. Use My Dashboard so the request carries the customer session and same-origin CSRF token safely.

Connect your bot via WebSocket. Pass API key as query param, X-Arena-Key header, or send an auth message after connecting.

wss://arena.angel-serv.com/ws/bot?key=YOUR_KEY

Connection Flow

1. Connect → receive connected message (includes grid_size, fog_radius)
2. Send select_loadout within 10 seconds
3. Receive loadout_confirmed
4. Wait for lobby or round_start
5. Optionally prefetch terrain from GET /api/v1/arena/map during intermission
6. Game loop: receive tick, send action

Watch the arena with a five-second presentation delay. No authentication is required, and the connection is receive-only.

The delay applies to ordered arena_state and lobby_state gameplay snapshots. heartbeat and service_status control messages remain immediate.

wss://arena.angel-serv.com/ws/spectator

Messages Received

Example arena_state

{
  "type": "arena_state",
  "tick": 342,
  "round_tick": 142,
  "bots": [
    {"bot_id": "uuid", "name": "MyBot", "position": [1050, 1020],
     "hp": 120, "max_hp": 160, "weapon": "sword",
     "is_alive": true, "avatar_color": "#ff0000",
     "is_dodging": false, "is_stunned": false}
  ],
  "safe_zone": {"center": [1000,1000], "radius": 800},
  "pickups": [{"pickup_type": "health_pack", "position": [900, 1100]}],
  "kill_feed": [{"killer": "BotA", "victim": "BotB", "weapon": "bow"}],
  "obstacles": [{"x": 100, "y": 200, "width": 60, "height": 40}],
  "waiting_bots": [{"name": "NewBot", "weapon": "bow"}]
}

Spectators receive world coordinates (floats), not grid coordinates. Bots in waiting_bots will join next round.

{
  "type": "connected",
  "bot_id": "uuid",
  "arena_size": [2000, 2000],
  "grid_size": [100, 100],
  "cell_size": 20,
  "fog_radius": 7,
  "available_weapons": ["sword", "bow", "daggers", "shield", "spear", "staff", "grapple"],
  "stat_budget": 20,
  "stat_min": 1,
  "stat_max": 10,
  "timeout_seconds": 10,
  "last_loadout": null
}

last_loadout contains your previous loadout if you have one (weapon, stats, fallback). Use this to auto-reselect your last loadout. stat_budget is the total stat points to distribute (default 20), each stat between stat_min (1) and stat_max (10).

{
  "type": "loadout_confirmed",
  "weapon": "sword",
  "stats": {"hp": 6, "speed": 6, "attack": 5, "defense": 3},
  "computed": {
    "max_hp": 160,
    "move_speed": 6.0,
    "attack_mult": 1.5,
    "defense_red": 0.09,
    "attack_range": 1,
    "cooldown_seconds": 0.5,
    "weapon_damage": 25
  },
  "position": [850, 1000]
}

{
  "type": "lobby",
  "bots_connected": 5,
  "bots_needed": 2,
  "countdown": 8,
  "players": [
    {"name": "BotA", "avatar_color": "#ff0000", "weapon": "sword"}
  ]
}

Sent once at the start of each round. Use GET /api/v1/arena/map to fetch the terrain payload for the current or next round.

{
  "type": "round_start",
  "round_number": 12,
  "round_modifier": "pickup_surge",
  "round_modifier_label": "Pickup Surge",
  "position": [42, 50],
  "bots_in_round": 15,
  "safe_zone": {
    "center": [50, 50], "radius": 71,
    "target_center": [45, 55], "target_radius": 9
  }
}

All positions are [col, row] grid coordinates (integers). Zone radius is in tiles.

The terrain grid is static for the entire round and is never repeated in tick messages. Cache it from REST. Obstacles are not sent in nearby_entities — terrain is the only way to know where walls are. If features_pending is true, fetch again after round_start for the active mode and round features.

{
  "status": "ok",
  "width": 100, "height": 100,
  "cell_size": 20,
  "terrain": [
    [".", ".", "#", ".", ".", ".", ".", "."],
    [".", "#", "#", ".", "~", "~", ".", "."],
    [".", "#", "#", ".", ".", ".", ".", "."],
    [".", ".", ".", ".", ".", ".", "#", "#"]
  ],
  "legend": {".": "ground", "#": "wall", "V": "void", "~": "water"}
}

Terrain Cell Types

How to Use Terrain

• terrain[row][col] — row-major 2D array. Access with terrain[y][x] where position is [x, y] (col, row).
• Before sending move in a direction, check that the destination cell is not # or V.
• move_to uses server-side A* pathfinding that automatically routes around walls.
• Walls block projectiles (bow arrows). Use walls as cover against ranged attackers.
• Terrain changes each round (obstacles are randomized), so always re-cache via GET /api/v1/arena/map.
• 20–30 obstacles per round, typically resulting in ~5–15% wall cells.

Example: Check if direction is walkable (Python)

def can_move(terrain, pos, direction):
    """Check if moving from pos=[col,row] in direction=[dx,dy] is walkable."""
    new_col = pos[0] + direction[0]
    new_row = pos[1] + direction[1]
    if 0 <= new_row < len(terrain) and 0 <= new_col < len(terrain[0]):
        return terrain[new_row][new_col] in (".", "~")
    return False

Sent every game tick. Contains your state and visible entities within fog_radius. All positions are [col, row] grid coordinates.

{
  "type": "tick",
  "tick": 342,
  "tick_number": 342,
  "fog_radius": 7,
  "your_state": {
    "bot_id": "uuid",
    "position": [52, 51],
    "hp": 120, "max_hp": 160,
    "speed": 6.0,
    "weapon": "sword",
    "cooldown_remaining": 0.2,
    "weapon_ready": false,
    "is_alive": true,
    "kill_streak": 3,
    "round_kills": 5,
    "dodge_cooldown": 0,
    "invuln_ticks": 0,
    "stun_ticks": 0,
    "facing": [0, 1],
    "recently_disrupted_ticks": 0,
    "brace_ready": false,
    "bow_charge_ticks": 3,
    "bow_charge_level": 0.5,
    "charged_shot_ready": true,
    "hazard_key_active": false,
    "hazard_key_ticks": 0,
    "bounty_token_bonus": 0,
    "shield_absorb": 0,
    "effects": [{"name": "speed_boost", "ticks": 20}],
    "last_action_result": {
      "action": "attack", "result": "hit",
      "target": "enemy_id", "damage": 35.5
    },
    "hits_received": [
      {"attacker_id": "enemy_id", "damage": 15, "weapon": "bow"}
    ],
    "kill_feed": [
      {"killer": "MyBot", "victim": "FooBot", "weapon": "sword", "tick": 340}
    ],
    "in_safe_zone": true,
    "distance_to_zone_edge": 12,
    "zone_radius": 40,
    "zone_center": [50, 50],
    "zone_target_center": [45, 55],
    "zone_target_radius": 9,
    "grapple_charges": 2,
    "grapple_cooldown": 0.0
  },
  "nearby_mines": 0,
  "nearby_entities": [
    {
      "type": "bot", "bot_id": "enemy_id", "name": "EnemyBot",
      "position": [53, 52], "hp": 85, "max_hp": 120,
      "weapon": "bow", "is_alive": true, "avatar_color": "#0000ff",
      "last_action": "attack", "is_dodging": false, "is_stunned": false,
      "facing": [1, 0], "recently_disrupted_ticks": 0,
      "brace_ready": false, "bow_charge_level": 0.3, "charged_shot_ready": false,
      "rear_exposed": true, "near_impact_surface": false,
      "has_los": true, "attack_range": 7, "can_attack": true, "threat_score": 85.4
    },
    {
      "type": "pickup", "pickup_id": "p_123",
      "pickup_type": "health_pack", "position": [55, 51]
    },
    {
      "type": "burn_field", "id": "burn_staff_1",
      "position": [54, 52], "radius": 1, "ticks_left": 6, "active": true
    }
  ],
  "safe_zone": {
    "center": [50, 50], "radius": 40,
    "target_center": [45, 55], "target_radius": 9
  }
}

Grid-based: No obstacle entities in ticks — use the cached terrain grid from GET /api/v1/arena/map. Fog radius = 7 tiles (visible area is 15×15). Nearby bots also expose tactical reads like rear_exposed and near_impact_surface for backstab/slam logic.

Hints (only when no bots in fog range)

When no enemy bots are within your fog_radius, a hints array is included with directions to the nearest 3 bots and the nearest pickup of each type.

"hints": [
  {"hint_type": "bot", "direction": [0.7, -0.7], "distance": 342.5},
  {"hint_type": "pickup", "pickup_type": "health_pack",
   "direction": [0.5, 0.9], "distance": 180.3}
]

{
  "type": "kill",
  "victim_name": "FooBot",
  "victim_id": "uuid",
  "weapon_used": "sword",
  "your_kill_streak": 3,
  "your_round_kills": 5
}

{
  "type": "death",
  "killed_by": "killer_uuid",
  "killer_name": "EnemyBot",
  "weapon_used": "bow",
  "damage": 45.5,
  "your_kills_this_life": 2,
  "respawn": false
}

respawn indicates whether you will respawn this round. When false, wait for round_end then round_start.

{
  "type": "respawn",
  "position": [1500, 1200],
  "hp": 160
}

{
  "type": "round_end",
  "round_number": 12,
  "your_stats": {"kills": 5, "deaths": 2, "damage": 750},
  "round_winner": "ChampionBot",
  "next_round_in": 10
}

Non-fatal error. Your bot stays connected.

{
  "type": "error",
  "message": "Invalid action",
  "code": "INVALID_ACTION",
  "details": "action 'fly' is not recognized"
}

Your bot has been disconnected. Common reasons: AFK timeout, rate limiting, admin action, or ban.

{
  "type": "kick",
  "reason": "AFK timeout"
}