Play your first ranked match
Your bot is a program on your machine. Give it the arena WebSocket address and a bot token. A starter connects, plays one complete match, and prints the outcome. If you already have a token, start with either kit below.
Get a bot token
Open Account and bots. Sign in with your owner key, or redeem the operator's single-use invite. Create a bot and copy the token shown once. Keep it outside source control. Set ARENA_TOKEN in the environment of the process that will run the bot. Owner keys manage bots and versions. Bot tokens authenticate a playing program.
Run all commands from a directory you control. The quickstart commands below use this server's address. If the operator moves the server, reopen this guide at the new address.
TypeScript with Node 24
Download the three TypeScript starter files into one directory. The policy chooses an action, and the client handles WebSocket authentication, deadlines and reconnects. Run these commands in PowerShell. The credential prompt appears only when the environment has no token.
New-Item -ItemType Directory -Force arena-ts | Out-Null
Set-Location arena-ts
$base = 'https://arena.natural20.com'
foreach ($file in 'bot.ts','strategy.ts','package.json') {
Invoke-WebRequest "$base/download/bots/ts-starter/$file" -OutFile $file
}
npm install --no-audit --no-fund
if (-not $env:ARENA_TOKEN) {
$env:ARENA_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host -AsSecureString 'Bot token')).Password
}
$env:ARENA_URL = 'wss://arena.natural20.com/bot'
$env:ARENA_VERSION = 'v1'
$env:ARENA_MATCHES = '1'
npm start
In Bash, set the same environment variables and run the kit with Node 24.
mkdir -p arena-ts && cd arena-ts
base='https://arena.natural20.com'
for file in bot.ts strategy.ts package.json; do
curl --fail --silent --show-error "$base/download/bots/ts-starter/$file" -o "$file"
done
npm install --no-audit --no-fund
if [ -z "${ARENA_TOKEN:-}" ]; then read -rs -p 'Bot token: ' ARENA_TOKEN; echo; fi
export ARENA_TOKEN ARENA_VERSION=v1 ARENA_MATCHES=1
export ARENA_URL='wss://arena.natural20.com/bot'
npm start
Individual files are available as bot.ts, strategy.ts and package.json.
Python with Python 3.11 or later
Download bot.py and requirements.txt into one directory. From PowerShell, run the following.
New-Item -ItemType Directory -Force arena-py | Out-Null
Set-Location arena-py
$base = 'https://arena.natural20.com'
foreach ($file in 'bot.py','requirements.txt') {
Invoke-WebRequest "$base/download/bots/py-starter/$file" -OutFile $file
}
python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt
if (-not $env:ARENA_TOKEN) {
$env:ARENA_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host -AsSecureString 'Bot token')).Password
}
$env:ARENA_URL = 'wss://arena.natural20.com/bot'
$env:ARENA_VERSION = 'v1'
$env:ARENA_MATCHES = '1'
.\.venv\Scripts\python bot.py
In Bash, use the same download loop with bot.py requirements.txt and py-starter in the URL. Set the environment as in the TypeScript example, create the environment with python3 -m venv .venv, then run .venv/bin/python -m pip install -r requirements.txt and .venv/bin/python bot.py.
Install the dependency once. On an offline machine, use a populated npm cache or a wheelhouse containing the package pinned by the kit. Gameplay uses the arena address you configure.
Confirm the match
A bot first receives queued, then hello, one or more observation messages, and end. The initial observation is tick zero. Other players or a house bot can fill the opponent seat. The end frame gives the match ID, result and replay path. Open recent matches to watch the recording or inspect its statistics. A fresh version needs 30 rated games under default settings to enter the leaderboard.
Set ARENA_MATCHES to a positive number to stop after that many endings. Remove it to keep playing. Set ARENA_LADDER to an accessible ladder ID to enter that competition. The default is public. Update ARENA_VERSION when you publish a changed policy. The first version of a new bot is v1.
Write your own bot
Implement the short message loop in the protocol guide. Choose actions with the combat guide and test them before queuing with the offline simulator. Coding agents can retrieve the same guides in Markdown through llms.txt.