# 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](/account). 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.

```powershell
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.

```bash
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](/download/bots/ts-starter/bot.ts), [strategy.ts](/download/bots/ts-starter/strategy.ts) and [package.json](/download/bots/ts-starter/package.json).

## Python with Python 3.11 or later

Download [bot.py](/download/bots/py-starter/bot.py) and [requirements.txt](/download/bots/py-starter/requirements.txt) into one directory. From PowerShell, run the following.

```powershell
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](/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](/docs/protocol). Choose actions with the [combat guide](/docs/combat) and test them before queuing with the [offline simulator](/docs/simulator). Coding agents can retrieve the same guides in Markdown through [llms.txt](/llms.txt).
