Step-by-step guide for beginners
What you need
- A FlipSight account.
- One bot photo: a GIF, JPG or PNG file of 5 MB or less, at least 175 px wide and tall.
- Your own computer to run the bot Your bot's moves are calculated on the computer where the connector runs. Even with the same engine, strength can differ with the computer's speed and the engine settings, and if you change the computer or the settings, the rating can move to match.
- Python 3, a free program that runs the connector. Version 3.9 or later works; 3.11 or later is recommended. You check it in step 5.
- Your bot engine. A practice engine for testing is included with the connector.
1. Register your bot
Sign in and open the bot page (othelloclub.com/en/flipsight/lab). In the Register my bot box at the top, enter a name in Bot name (2–24 characters). Leave Supported games with only Standard checked for now. Choose a picture in Upload bot photo, then press the Register my bot button.
Success looks like this: the Connection token (shown only once) box appears with a long text starting with fsbm_.
2. Keep the token
This long text is the token, a password just for your bot. The connector uses it to prove to the server that it speaks for this bot. Copy all of it and paste it somewhere temporary, such as a text editor. Once you close the box, you cannot see the same token again.
Treat the token like a password. Do not show it to anyone or post a screenshot of it. If you lose it or someone sees it, open Manage in the bot list and press Issue connection token. When you get a new token, the old one stops working immediately.
3. Download the connector
Press FlipSight bot connector bundle (.zip) to download the ZIP file and extract it. This guide calls the extracted folder the "bot folder". Put it somewhere easy to find, such as the desktop.
Success looks like this: the bot folder contains the README.md file and the tools folder.
4. Open a terminal in the bot folder
A terminal is a window where you type commands. Open it as follows for your system.
macOS: press Command+Space, type Terminal and open it. Type cd and one space, drag the bot folder into the window, then press Enter.
Linux: in the file manager, right-click the bot folder and choose Open in Terminal. The menu name can differ between distributions. If there is no such menu, open a terminal and use cd as on macOS.
Windows: open the bot folder in File Explorer. Type powershell in the address bar at the top and press Enter. A PowerShell window opens in that folder.
Check: type the command below and press Enter. Success means README.md and tools appear in the list. This command is the same on macOS, Linux and Windows PowerShell.
ls5. Check Python
In the same window, copy the one command for your system, paste it and press Enter. You can use the copy button at the top right of each code box.
macOS / Linux
python3 --versionWindows PowerShell
py --versionSuccess looks like this: a version starting with 3, such as Python 3.11.9. Version 3.9 or later works. If the command is not found, install Python as below, close the window and start again from step 4.
macOS: download the macOS installer (.pkg) from python.org and install it. Then run Install Certificates.command once from the Python folder in Applications. This prepares the certificates needed for secure (HTTPS) connections.
Linux: install python3 with your distribution's software manager or package manager.
Windows: install the Python install manager from python.org.
6. Enter the token
Put the token into an environment variable, a temporary setting that exists only inside this terminal window. Its name is FS_BOT_TOKEN. Copy the one-line command for your system below, paste it and press Enter once. Bot token then appears and waits for your input. Now paste the token you copied in step 2 and press Enter.
macOS / Linux
printf 'Bot token: '; read -r -s FS_BOT_TOKEN; printf '\n'; export FS_BOT_TOKENWindows PowerShell
$env:FS_BOT_TOKEN = [Net.NetworkCredential]::new('', (Read-Host 'Bot token' -AsSecureString)).PasswordOn macOS and Linux the pasted token is not shown, and on Windows you see * instead of its characters. Both are normal. Because the token is not written into the command, it does not stay in the command history. The setting lasts only in this window. If you closed it or opened a new window, repeat steps 4 and 6.
In PowerShell, paste the token with Ctrl+V.
Success looks like this: the prompt for the next command returns without an error.
7. Start the connector
In the same window, copy the command below as it is, paste it and press Enter. Do not change the file names in it. Your bot connects with the practice engine, a very weak engine that plays the legal square with the lowest number.
macOS / Linux
python3 tools/bot_match_client.py --engine-threads 1 --engine 'python3 tools/bot_match_example_engine.py'Windows PowerShell
py tools/bot_match_client.py --engine-threads 1 --engine 'py tools/bot_match_example_engine.py'It is normal for this command to produce no text and not return to the prompt while running. To keep your bot online, leave this window open with the connector and engine running, and prevent your computer from sleeping. Closing this window or pressing Ctrl+C stops the connector and engine, and your bot goes offline. Run the command above again to bring it back online. The connector automatically accepts match requests from other bots.
While the bot runs with the practice engine it gets no automatic matches, and bot-vs-bot games it plays, even ones you request, are not rated. Restart it with your own engine (step 10) and it is matched and rated from then on.
Success looks like this: in the Registered bots list on the bot page, the dot to the right of your bot's name is green. Hovering over it shows Online.
8. Test with a first game
On the bot page, choose your bot in My playing bot. Pick any bot in the FlipSight bots list, press Challenge and confirm in the window that opens. In every game type the server calculates the FlipSight bot's moves, so you do not need to keep the game room open.
Success looks like this: the game room shows two boards and a disc is placed on each of your bot's turns. The practice engine is very weak, so losing is normal.
9. Keep it running after closing the window (optional)
After the first game, stop the connector with Ctrl+C in the window from step 7. Restart it there with the command below. Keep the computer awake.
macOS / Linux
Use screen and replace mybot with a different name for each bot. After starting, press Ctrl+A, then D to detach and close the window. To stop this bot, reattach with the command below and press Ctrl+C.
Start
screen -S mybot python3 tools/bot_match_client.py --engine-threads 1 --engine 'python3 tools/bot_match_example_engine.py'Stop
screen -r mybotWindows PowerShell
Windows: a minimized window appears in the taskbar and the bot runs in it. You can close the current PowerShell window. To stop it, open the minimized window and press Ctrl+C, or close that window.
Start
Start-Process py -ArgumentList 'tools/bot_match_client.py --engine-threads 1 --engine "py tools/bot_match_example_engine.py"' -WorkingDirectory $PWD -WindowStyle Minimized10. Switch to your own engine
After checking the connection with the practice engine, switch to your own. Use the dedicated options below for Edax or Egaroucid, --nboard for other compatible engines, or JSON for your own engine. Keep the same token.
- Edax: --edax
- Egaroucid: --egaroucid
- NBoard engines such as NTest: --nboard
- Self-made engine: connect through JSON
Check a variant game (Anti, 10x10, Octagon, classic Reversi) in Supported games only when your engine knows its rules. Other bots and people can challenge your bot in every checked game. To change it, open Manage in the bot list, edit Supported games and press Save. You cannot change it while a game is running or a challenge is waiting.
Common problems
| Symptom | Cause and fix |
|---|---|
| The bot shows a grey dot (offline). | Check that the connector window is still running. It stops when you close the window, press Ctrl+C or the computer sleeps. |
It says the command was not found.command not found / is not recognized | Python is missing, or the window was not reopened after installing it. See step 5, open a new window and start again from step 4. |
It says the file cannot be opened.can't open file | You ran it outside the bot folder. Move to the bot folder as in step 4 and check with ls that README.md and tools are listed. |
It says the token is missing and exits.FS_BOT_TOKEN is missing or invalid | This window has no token. If you opened a new window, repeat step 6. |
It says the token was rejected and stops.Bot credential rejected | The token was pasted incorrectly or is an old one. After you issue a new token or disable the bot, the old token no longer works. Start again from step 6 with the latest token. |
The same error line keeps appearing.Connection/state error | Check the internet connection. On macOS, check that you ran Install Certificates.command from step 5. If it appears only during games, the server may be rejecting your engine's move as illegal. The connector sends the same move again, so the engine has to be fixed. |
| The challenge button does not work, or the challenge is not accepted. | Select My playing bot and check that both bots are online. The opponent must accept direct challenges and have a slot available. An unanswered challenge expires after 120 seconds. |
The bot makes no move and then loses on time or the game is aborted.Engine failed for match | The engine did not answer in time or its answer had the wrong format. Check the engine command and its one-line JSON output. If a bot makes no first move within 30 seconds after the start, the game is aborted. |
| No variant game challenges arrive. | The challenge window lists only games that both bots support. Check that the game is checked in your bot's Supported games and that the other bot supports it too. A bot connected with --edax or --nboard should have only Standard checked. |
Glossary
| Term | Meaning |
|---|---|
| API | An agreed way for programs to send requests and replies. The connector handles it for you. |
| Token | A password just for your bot. The connector uses it to prove to the server which bot it is. |
| Terminal | A window where you type commands. On Windows, use PowerShell. |
| Environment variable | A temporary setting passed to programs started from one terminal window. It disappears when the window closes. |
| JSON | A format for writing data as text. Example: {"move":19} |
| Engine | A program that looks at a position and chooses a move. |
| Adapter | A small program that converts data between your engine and the connector. |
| NBoard | An open format that Othello engines and board programs use to exchange positions and moves. Engines that support it, such as NTest, connect without an adapter. |
| Legal move | A square you may play now. The server lists them in legal_moves. |
Connecting your engine
Run each engine with no more than 4 threads. A bot match runs two games simultaneously, with at most 8 threads in total per match.
Edax: --edax
The installation and launch examples below use Edax 4.6 and Egaroucid for Console 7.8.2.
Edax 4.6 is not included with the connector. Download the file for your operating system from Assets on Edax 4.6, place it in the bot folder, and extract it with the preparation commands below. The Windows and Linux commands target x86-64 computers.
Windows PowerShell (x86-64): edax-4.6-MS-windows-x86.zip
Prepare (first time only)
Expand-Archive -LiteralPath edax-4.6-MS-windows-x86.zip -DestinationPath edax-4.6Start
py tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6\wEdax-x86-64.exe"Linux (x86-64): edax-4.6-linux-x86.tar.gz
Prepare (first time only)
mkdir -p edax-4.6
tar -xzf edax-4.6-linux-x86.tar.gz -C edax-4.6
chmod +x edax-4.6/lEdax-x86-64Start
python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/lEdax-x86-64"macOS: edax-reversi-4.6.tar.gz
There is no official macOS executable for Edax 4.6. Download Source code (tar.gz) and edax-4.6-linux-x86.tar.gz from the same release. Build the Mac executable from source; extract only the shared data/eval.dat file from the Linux archive. Xcode Command Line Tools are required. The preparation commands below compile the source.
Prepare (first time only)
xcode-select --installtar -xzf edax-reversi-4.6.tar.gz
mv edax-reversi-4.6 edax-4.6
mkdir -p edax-4.6/bin
tar -xzf edax-4.6-linux-x86.tar.gz -C edax-4.6 data/eval.dat
(cd edax-4.6/src && make build ARCH=native OS=osx)Start
python3 tools/bot_match_client.py --engine-threads 2 --edax "edax-4.6/bin/mEdax-native"Edax can also be connected with just its executable path using --edax below. No separate adapter is needed. The connector runs Edax over xboard and sends both remaining clocks before every move; Edax decides its own thinking time (connector v1.4.8 or later). Edax keeps its game and hash table through the board, and with --engine-ponder on it also searches during the opponent's time. --edax-protocol nboard keeps the older NBoard connection.
Replace the command path with the full path to your executable. Put paths containing spaces in double quotes. If the evaluation file is not found automatically, use --edax-eval to specify eval.dat.
An --edax or --nboard connection plays standard 8×8 games only. Keep only Standard checked in Supported games for this bot. If a variant game arrives, the connector does not ask the engine, no move is played, and the game is aborted or lost on time.
Egaroucid: --egaroucid
Prepare Egaroucid for Console. Select the console executable rather than the graphical application, and keep its resources folder in place. On macOS and Linux, use an executable built following the official instructions. The connector sends the position and remaining time with the native setboard, settime and go commands, so no adapter is needed.
Windows PowerShell
py tools/bot_match_client.py --engine-threads 2 --egaroucid "egaroucid\Egaroucid_for_console.exe"macOS / Linux
python3 tools/bot_match_client.py --engine-threads 2 --egaroucid "egaroucid/bin/Egaroucid_for_Console.out"Both modes support standard 8×8 only and run one engine per game when two games run together. --max-think-seconds is the per-move safety cap (10 seconds by default). If Egaroucid reaches that cap, the connector stops that search, plays a legal fallback move and restarts the engine on the next turn.
NBoard engines such as NTest: --nboard
NBoard is an Othello graphical application that can be used with NTest. The NBoard protocol is its published format for communicating with engines; connect engines that implement it, such as NTest, with --nboard. One engine per board stays running. Edax implements it too, but connect Edax with --edax above.
Windows PowerShell
py tools/bot_match_client.py --engine-threads 2 --nboard "path\to\engine.exe"macOS / Linux
python3 tools/bot_match_client.py --engine-threads 2 --nboard "path/to/engine"An --edax or --nboard connection plays standard 8×8 games only. Keep only Standard checked in Supported games for this bot. If a variant game arrives, the connector does not ask the engine, no move is played, and the game is aborted or lost on time.
Self-made engine: connect through JSON
Read this part only if you want to connect an engine you wrote yourself. If you use Edax, Egaroucid or an NBoard engine, you are already done above and can skip it.
Each time it is your bot's turn, the connector runs my_adapter.py once. It hands over the current position as one line (where the discs are, whose turn it is, which squares are legal, how much time is left), my_adapter.py answers with one square as one line, and the connector plays that move on the server. my_adapter.py is a small Python file in between that asks your engine for the move. The connector takes care of the server connection, the token and move submission, so this file never deals with them.
bot_match_client.py→ my_adapter.pybot_match_client.py← my_adapter.pyWhich kind is your engine?
- An engine that picks its move in Python code: use example A below.
- A program file that prints one answer line and exits each time it runs: use example B below.
- An executable that stays open and keeps exchanging commands: if it supports NBoard, connect it with --nboard above. For another protocol, adapt example B to that protocol and make my_adapter.py keep the engine open and loop, exchanging one line at a time.
Step 1: a file that only checks the connection (my_adapter.py)
In the bot folder (where README.md and tools are), create a file named my_adapter.py, paste the code below as it is and save it. This file uses no engine and simply answers with the first legal square. It is there to confirm the connection works before you attach your engine.
import json
import sys
def choose_move(position):
legal = position["legal_moves"]
return legal[0] if legal else -1
line = sys.stdin.readline()
position = json.loads(line)
move = choose_move(position)
print(json.dumps({"move": move}), flush=True)
Check input and output before connecting
The command in box 1 feeds the example position straight into the adapter. It should print one line: {"move": 19}. Once you see that line, the command in box 2 starts the connector with this adapter, in the window that has the token from step 6. Run the two boxes separately. If your engine reads this JSON format itself, you can put its command directly after --engine.
1. Test the adapter alone
macOS / Linux
printf '%s\n' '{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}' | python3 my_adapter.pyWindows PowerShell
'{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}' | py my_adapter.py2. Start the connector with the adapter
macOS / Linux
python3 tools/bot_match_client.py --engine-threads 2 --engine 'python3 my_adapter.py'Windows PowerShell
py tools/bot_match_client.py --engine-threads 2 --engine 'py my_adapter.py'Step 2: switch to a file that calls your engine
Once step 1 works, replace the whole content of my_adapter.py with example A or B below. Change only the lines marked EDIT and leave the rest as it is. Then run test command 1 above again and check that one answer line appears. Your engine chose the move, so a square other than 19 is normal.
Example A: an engine that picks its move with a Python function
This example assumes a file named my_engine.py with a search function that picks the move. At EDIT 1 change the file name and function name, and at EDIT 2 change the values passed in, to match your engine. The function should return the square number (0 to 63) or a coordinate such as d3.
import json
import sys
from pathlib import Path
from my_engine import search # EDIT 1: your engine file and function name
def think_ms(position):
# Time for this move: share the remaining clock over my remaining moves.
my_moves_left = position["board"].count(0) // 2 + 1
share = position["remaining_ms"] / my_moves_left
return int(min(share, position["budget_ms"]) * 0.8)
def choose_move(position):
if not position["legal_moves"]:
return -1
# EDIT 2: pass what your function needs
return search(
board=position["board"],
color=position["color"],
legal_moves=position["legal_moves"],
time_limit_ms=think_ms(position),
)
position = json.loads(sys.stdin.readline())
legal = position["legal_moves"]
try:
move = choose_move(position)
except Exception as error:
# The engine failed: note why in my_adapter.log and play the first legal square.
with open(Path(__file__).with_name("my_adapter.log"), "a") as log:
log.write(repr(error) + "\n")
move = legal[0] if legal else -1
print(json.dumps({"move": move}), flush=True)Example B: an engine that is a program file
This example assumes the program reads one line with 64 board characters, the side to move and the thinking time in milliseconds, and answers with one coordinate line such as D3 (. = empty, X = black, O = white). Every engine has its own format, so change the program file name at EDIT 1, the line sent to the engine at EDIT 2 and the part that reads the answer at EDIT 3 to match your engine.
my_adapter.py → my_engine
...........................OX......XO........................... X 1777my_engine → my_adapter.py
D3import json
import subprocess
import sys
from pathlib import Path
# EDIT 1: your engine program file (kept in the same folder as my_adapter.py)
ENGINE = Path(__file__).with_name("my_engine.exe" if sys.platform == "win32" else "my_engine")
def think_ms(position):
# Time for this move: share the remaining clock over my remaining moves.
my_moves_left = position["board"].count(0) // 2 + 1
share = position["remaining_ms"] / my_moves_left
return int(min(share, position["budget_ms"]) * 0.8)
def choose_move(position):
if not position["legal_moves"]:
return -1
# EDIT 2: build the line your engine reads
board = "".join(".XO"[cell] for cell in position["board"])
color = "X" if position["color"] == 1 else "O"
reply = subprocess.run(
[str(ENGINE)],
input=f"{board} {color} {think_ms(position)}\n",
text=True,
capture_output=True,
check=True,
timeout=position["budget_ms"] / 1000 * 0.9,
)
# EDIT 3: take the square out of your engine's answer
return reply.stdout.strip()
position = json.loads(sys.stdin.readline())
legal = position["legal_moves"]
try:
move = choose_move(position)
except Exception as error:
# The engine failed: note why in my_adapter.log and play the first legal square.
with open(Path(__file__).with_name("my_adapter.log"), "a") as log:
log.write(repr(error) + "\n")
move = legal[0] if legal else -1
print(json.dumps({"move": move}), flush=True)Thinking time: a bot game gives each bot 1 minute per board, so long thinking on one move quickly loses on time. think_ms in the examples divides the remaining time (remaining_ms) by your remaining moves to decide the time for this move. budget_ms is not the time to spend on this move. It is the longest the connector waits for the answer (10 seconds by default). If the answer comes later than that, the bot cannot continue on that board and loses it on time, so pass think_ms to your engine, not budget_ms.
When something breaks: if the engine call fails, the example files write the reason to my_adapter.log and play the first legal square instead. If the moves look odd, open that file first. The connector does not show the adapter's error messages on screen. Use print only for the one answer line and write any debug text to a file.
Speed: the connector keeps my_adapter.py running for each game and sends one line per move. A file that answers one line and exits, like the examples, is started again on the next move, so your engine also starts again each time. If the engine is slow to start or should keep its work from earlier moves, make my_adapter.py loop: read one line, answer one line, repeat. Do not read input to the end, and flush after every answer.
The rest of this part is reference material on what the connector and my_adapter.py exchange. If you use the example files above as they are, you do not need to read it.
Input JSON (connector → adapter)
This is example data sent by the connector, not executable code. Do not save it as a Python file. During a game, the connector sends the current data automatically on each turn.
Below is an example of the standard 8×8 starting position. In real games the connector fills in the current position. board lists squares from a1 to the right, then the next row; 0=empty, 1=black, 2=white. color=1 asks for a black move. legal_moves lists the squares you may play. remaining_ms is the remaining game clock and budget_ms is the longest the connector waits for the answer to this move, both in milliseconds (1000 = 1 second). Fields and examples for variant games are in the variant games section below.
{"board":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,1,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"color":1,"legal_moves":[19,26,37,44],"game_mode":"std","board_size":8,"blocked_squares":[],"placed":{"1":0,"2":0},"remaining_ms":60000,"match_id":123,"leg":0,"revision":0,"history":[],"round_no":null,"room_created_at":null,"budget_ms":10000}Response JSON (adapter → connector)
Write one of the replies below as a single JSON line ending with a newline. move is a square number or a coordinate, case-insensitive. On 8×8, d3 is (3−1)×8+3 = 19. Always choose from the legal_moves you received. In bot pairs with no legal move, send -1 or pass; the server resolves forced passes in human games. Write only the reply line to stdout, with no other messages.
{"move":19}{"move":"d3"}{"move":-1}Optional: add environment to a reply to report the engine's actual threads, hash MB and pondering (connector v1.4.6 or later). The connector accepts only in-range numbers and true/false and shows them in the bot information. A custom adapter that adds eval has it sent with the move in bot matches (for example {"move":19,"eval":1.5}). The value is your evaluation after the move in discs from your side, up to the game's playable squares; --edax, --egaroucid and NBoard engines send it by themselves once you update to v1.5.3.
{"move":19,"environment":{"engine_threads":1,"hash_mb":32,"ponder":false}}Downloads
FlipSight bot connector bundle (.zip)
GitHub: flipsight-othello-bot-connector
The first item is a .zip archive containing the README and the connector/example engine in tools/. The API specification (.json) and user guide (.md) are separate downloads.
Implementing the API yourself
Stop the practice connector first. Open the stream with the token from step 6. Keep one connection per token. Each line is one JSON event.
Event stream
curl -N 'https://othelloclub.com/flipsight_api/bot-stream' \
-H "Authorization: Bearer $FS_BOT_TOKEN"
Windows PowerShell
curl.exe -N https://othelloclub.com/flipsight_api/bot-stream -H "Authorization: Bearer $env:FS_BOT_TOKEN"After hello, you receive state. This example shows the relevant fields for bot 2.
{
"type": "state",
"view": "agent",
"bot": {
"id": 2
},
"matches": [
{
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2,
"state": {
"legs": [
{
"turn": 1,
"black_participant": 0,
"revision": 1,
"status": "active",
"legal_moves": [2, 3, 12, 25, 42, 44, 45]
},
{
"turn": 1,
"black_participant": 1,
"revision": 0,
"status": "active",
"legal_moves": [2, 3, 12, 25, 42, 44, 45]
}
]
}
}
]
}Your bot plays black (1) on the second board (leg 1). Since turn is 1, pick a move from legal_moves and send it with this board’s revision. To play a real move, set the token in a second terminal as in step 6 and use the current match values.
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Event stream
| Type | Description |
|---|---|
hello | Connection confirmed. bot_id identifies your bot. |
state | Replace your list of active games and invitations. You can use agent_accept for a pending invitation when you are bot_b. |
match | Update the game with this id. Check each active board for your turn. |
ping | Heartbeat every 10 seconds. No reply needed. |
closing | Last line before the server closes the stream. If reason is overflow (too many unsent lines) or server_shutdown, reconnect and catch up from state. replaced means the same token is in use somewhere else. Do not reconnect at once: wait at least 30 seconds, and longer if it happens again. Use each token in one place only. |
Match object (matches[])
| Field | Type | Description |
|---|---|---|
id | integer | Match ID (negative for games against a person) |
kind | string | human for games against a person |
bot_a | integer | Bot ID of participant 0 (0 for a person) |
bot_b | integer | Bot ID of participant 1 (0 for a person) |
game_mode | string | Game (std, anti, grand, octagon, reversi) |
time_limit_sec | integer | Seconds given per leg, per color |
status | string | pending, running, finished, aborted, rejected, expired |
expires_ms | integer | Acceptance deadline (milliseconds) |
ranked | boolean | Whether the match is rated |
state.status | string | active, finished or aborted |
state.game_mode | string | Game (std, anti, grand, octagon, reversi) |
state.board_size | integer 8 | 10 | Squares per side, 8 or 10 |
state.blocked_squares | integer[] | Unusable squares (Octagon only, not sorted) |
state.legs | array | Legs (2 between bots, 1 against a person) |
state.totals | [integer, integer] | Combined adjudicated scores per participant (use discs if result_discs is absent) |
state.winner | integer | null | Winning participant 0 or 1, null for a draw |
state.finish_reason | string | null | discs, timeout, double_timeout, disconnect, no_first_move |
Leg object (state.legs[])
| Field | Type | Description |
|---|---|---|
board | integer[64 | 100] | 64 / 100 squares, 0=empty 1=black 2=white |
turn | integer | Color to move, 1 (black) or 2 (white) |
legal_moves | integer[] | Legal squares for the color to move. Empty for finished legs |
placed | {"1": integer, "2": integer} | Discs placed per color, keys "1" (black) and "2" (white) |
black_participant | integer | Participant who plays black in this leg |
clocks_ms | [number, number] | Remaining-time baselines in color order (black, white) |
turn_started_ms | integer | Server time when the current turn started |
revision | integer | Increases by 1 whenever this leg changes |
status | string | active, finished, timeout, stopped |
history | array | Moves played (color, participant, move, at_ms, eval) |
discs | [integer, integer] | Disc counts in color order (black, white) |
result_discs | [integer, integer] (optional) | Optional adjudicated score [black, white] for a leg lost on time; total it instead of discs. Scores for the side that timed out and its opponent: std and reversi 0 to 64, grand 0 to 100, octagon 0 to 88, anti 64 to 0. The other leg continues, and the totals decide the winner after both legs end. Older finished records are not recalculated. |
When a game ends, the last match event also carries record, the game record. Save it as it is to keep the whole game. Game records
State synchronization
If the connection drops or sends nothing for 15 seconds, reconnect with delays increasing from 1 to 30 seconds. Discard older states. For human games, compare room_created_at, round_no, then revision. Retry a lost move only if it is still your turn at the same board revision.
Report engine details with agent_environment at startup and when they change. For automatic matching, v2 allows up to 10 stream connections and zero agent_poll calls in the last 10 minutes online.
Authentication
Send HTTPS JSON POST requests with Authorization: Bearer. Tokens belong to one bot. Never put them in URLs, public source code or logs.
Content-Type: application/json
Authorization: Bearer <FS_BOT_TOKEN>POST https://othelloclub.com/flipsight/bot_match_api.php
Connector options
Options for tools/bot_match_client.py. Exactly one of --engine and --nboard / --edax / --egaroucid is required. The token is never an option; it is read only from the FS_BOT_TOKEN environment variable. Exit codes: 0 normal stop, 2 token rejected, 3 --max-runtime reached.
| Parameters | Description |
|---|---|
--engine "COMMAND" | Starts this command once per game and exchanges one JSON line per move without closing its input. An engine that answers one line and exits is started again on the next move. |
--nboard "COMMAND" | Keeps one NBoard engine per leg, two in total. Standard (std) only. |
--edax PATH | Edax can also be connected with just its executable path using --edax below. No separate adapter is needed. The connector runs Edax over xboard and sends both remaining clocks before every move; Edax decides its own thinking time (connector v1.4.8 or later). Edax keeps its game and hash table through the board, and with --engine-ponder on it also searches during the opponent's time. --edax-protocol nboard keeps the older NBoard connection. |
--edax-eval PATH | Path to Edax eval.dat. If omitted, data/eval.dat is located in the executable directory or its parent. |
--edax-protocol xboard|nboard | Connection used with --edax. The default, xboard, lets Edax run its own clock and ponder (v1.4.8 or later). nboard is the connection used up to v1.4.7: the connector sets the time for each move and Edax does not ponder. |
--egaroucid PATH | Prepare Egaroucid for Console. Select the console executable rather than the graphical application, and keep its resources folder in place. On macOS and Linux, use an executable built following the official instructions. The connector sends the position and remaining time with the native setboard, settime and go commands, so no adapter is needed. |
--egaroucid-level N | Used with --egaroucid. 1 to 60 starts Egaroucid at that level (-level N) and sends no remaining time (settime); 0 or omitted keeps time mode, which follows the game clock. Level mode has no command to stop a search early: if a move goes past the --max-think-seconds cap, the connector stops the engine and plays a legal fallback move. Choose a level that finishes well within the game clock. |
--nboard-depth N | Sends set depth N to the NBoard engine. 0 to 60; 0 keeps the engine default. With --edax this is the Edax level (20 means L20); without it the level is 60. Edax plays its best move so far when it reaches the level or runs out of time for the move, whichever comes first. With --edax it is sent as sd N over xboard. |
--max-think-seconds S | Maximum seconds to wait for the engine per move. Default 10, maximum 300. Never longer than the remaining clock minus 0.75 seconds. This is a connector safety cap; the server has no per-move time limit. Set 0 to remove the per-move cap and use the remaining game clock. The game clock is set by the site and cannot be changed by the connector: bot pairs and automatic bot matches give each color 60 seconds per board, and a person who challenges your bot directly picks the clock. With --edax, Edax sets the time for each move from its own clock within this cap; when the cap is reached, the connector makes Edax play its best move so far at once. |
--engine-name NAME | Engine name reported in the bot information (120 characters or fewer). Do not include commands or paths. |
--engine-threads N | Threads the engine uses per game , shown in the user record. With --edax or --egaroucid the engine runs with this value (default 4 when the computer has more than 4 logical CPUs, otherwise 1); with --engine it is sent as engine_threads in each request. Use at most 4 threads per engine, with at most 8 total for a bot match running two games simultaneously. With --engine/--nboard, omission prompts for input; background or unattended runs require this option. |
--engine-hash-mb MB | Hash-table size per engine in MB. With --edax or --egaroucid the engine table is set to the largest power-of-two size not above this value (Edax -h, Egaroucid -hash) and that size is reported; without it Edax uses edax.ini and Egaroucid 32 MB. Other engines only report the value; their settings are not changed. Each engine has its own table, so a bot match playing two games at once uses twice as much. |
--engine-ponder on|off | Pondering (searching during the opponent's time). With --egaroucid, on starts Egaroucid with -ponder and reports On; it uses CPU during the opponent's turn too. With --edax (connector v1.4.8 or later), on makes Edax ponder over xboard (hard) and reports On; with --edax-protocol nboard Edax does not ponder, so on is rejected. Other engines only report their actual setting. |
--cpu-name NAME | CPU name to report (120 characters or fewer). Detected automatically when omitted. |
--once-match ID | Handles only this match and exits when it ends (finished, aborted, expired, rejected). Negative human-game IDs work too. For tests, combine it with --max-runtime. |
--max-runtime S | Cleans up the engines and exits after this many seconds (exit code 3). |
--save-games DIR | When on, every game that ends from then on is saved to DIR/games-YYYY-MM.ndjson, one game record per line (off by default). Games that ended while the connector was stopped or the stream was down are filled with agent_games on reconnecting, from the newest saved game. A game takes about 4 KB (about 6 KB on 10×10), so 1,400 games a day come to about 6 MB a day and 180 MB a month. Delete old month files yourself when you no longer need them. |
--timing-log PATH | Appends one line per move showing where the time went (receiving the move, waiting for a free search, the engine, sending the move). Off by default; nothing extra is sent to the server. |
--api URL, --stream-url URL | API and stream addresses. Normally keep the defaults. Only HTTPS is accepted, and because the token is sent along, the stream must be on the API host. |
Variant games
A bot receives only the games checked in Supported games. The game_mode in engine requests and match state tells you the game. The server calculates board size, blocked squares and legal squares, so the engine only has to choose from the legal_moves it receives. Do not generate 10×10 or classic Reversi moves with standard 8×8 move generation.
| Game | game_mode | Board |
|---|---|---|
| Standard | std | 8×8 |
| Anti | anti | 8×8 |
| Grand (10x10) | grand | 10×10 |
| Octagon | octagon | 10×10 (88) |
| Classic Reversi | reversi | 8×8 |
Common rules: Black (1) moves first. Both legs start from the same position with colors swapped and run at the same time. In bot pairs, when you have no legal move, legal_moves arrives as an empty array and the bot must send move=-1 (pass) itself. The server does not pass for you, and your clock keeps running. Passing while a legal move exists is illegal. A leg ends when neither color can move. New paired matches add each normally finished leg’s empty squares to the color with more discs, then combine both scores. Anti rewards the lower adjusted total; tied disc counts receive no empty squares. Equal totals are a draw. All bot matches start from a random position containing 12 discs. Every game type gives each bot 1 minute per board.
Anti: placing and flipping work as in standard Othello. The side with fewer discs over both legs wins.
10x10: standard rules on a 10×10 board (100 squares). Its initial setup is the four center squares; bot pairs add 8 random moves and start at 12 discs.
Octagon: the same board and starting setup as 10x10, but three squares in each corner, 12 in total, are unusable (88 playable squares). Blocked squares arrive as square numbers in blocked_squares and as 0, the same value as empty, in board. The array is not in numeric order. You cannot play on a blocked square, and lines of discs stop there.
Classic Reversi: by its rules the game starts on an empty board. While any of the four center squares (27, 28, 35, 36) is empty, you place only there and nothing is flipped. Once all four are filled, standard rules apply. Each color places at most 32 discs, including the first four moves. placed counts the discs each color has placed so far; its keys are the strings "1" (black) and "2" (white). Bot pairs start after the server has played 12 random placements, including the four center moves, so in the first request the two placed counts add up to 12 (usually {"1":6,"2":6}). A color that has placed all 32 receives an empty legal_moves and sends -1 on each of its turns.
Engine request examples by game
Examples of Black's first request that the connector sends to an --engine engine, generated with the rule code. Real games of every type start from a random 12-disc position, so board and legal_moves differ in every game. To keep these examples fixed, their opening moves were chosen near the center of the board. match_id and the clock values also differ in real games.
Anti (anti)
Input JSON (connector → adapter)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [2, 3, 12, 25, 42, 44, 45],
"game_mode": "anti",
"board_size": 8,
"blocked_squares": [],
"placed": {
"1": 4,
"2": 4
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}Response JSON (adapter → connector)
{"move":2}Grand (10x10) (grand)
Input JSON (connector → adapter)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [13, 14, 25, 42, 63, 65, 66],
"game_mode": "grand",
"board_size": 10,
"blocked_squares": [],
"placed": {
"1": 4,
"2": 4
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}Response JSON (adapter → connector)
{"move":13}Octagon (octagon)
Input JSON (connector → adapter)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 2, 2, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [13, 14, 25, 42, 63, 65, 66],
"game_mode": "octagon",
"board_size": 10,
"blocked_squares": [0, 1, 10, 8, 9, 19, 80, 90, 91, 89, 98, 99],
"placed": {
"1": 4,
"2": 4
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}Response JSON (adapter → connector)
{"move":13}Classic Reversi (reversi)
Input JSON (connector → adapter)
{
"board": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"color": 1,
"legal_moves": [18, 25, 33, 41, 42, 50, 51],
"game_mode": "reversi",
"board_size": 8,
"blocked_squares": [],
"placed": {
"1": 6,
"2": 6
},
"remaining_ms": 60000,
"match_id": 123,
"leg": 0,
"revision": 0,
"history": [],
"round_no": null,
"room_created_at": null,
"budget_ms": 10000
}Response JSON (adapter → connector)
{"move":18}Engine request fields
| Field | Type | Description |
|---|---|---|
game_mode | string | One of std, anti, grand, octagon, reversi. XOT in human games arrives as std. |
board_size | integer 8 | 10 | 8, or 10 for grand and octagon. |
board | integer[board_size²] | Array of length board_size². Read from a1 to the right, then the next row. 0=empty (including Octagon's blocked squares), 1=black, 2=white. |
blocked_squares | integer[] | Unusable Octagon squares. An empty array in other games. |
placed | {"1": integer, "2": integer} | Discs placed so far per color, including the random opening moves; keys are the strings "1" and "2". Used for the 32-disc limit of classic Reversi. |
legal_moves | integer[] | Squares you may play now. If empty, answer move=-1. |
color | integer 1 | 2 | Color to move. 1=black, 2=white. |
budget_ms | integer | Time allowed for this move in milliseconds: the smaller of --max-think-seconds and the remaining clock minus 0.75 seconds. The connector stops the engine when it is exceeded. |
remaining_ms | integer | Your color's remaining clock in this leg, in milliseconds, after subtracting the time already used this turn. |
match_id | integer ≠ 0 | Match id. Negative (-room number) for human games. |
leg | integer 0 | 1 | Leg number 0 or 1. Always 0 for human games. |
revision | integer | State number of this leg. Send it unchanged with agent_move. |
history | array | Moves played in this leg. Decide from board. |
round_no | integer | null | Round number of a human game. null for bot pairs. |
room_created_at | string | null | Creation time of the human game room. null for bot pairs. |
engine_threads | integer (optional) | Present only when the connector was started with --engine-threads. The number of threads your engine may use for this game; size your search to it. |
Challenging another bot to a variant
Add game_mode to agent_challenge; it defaults to std. Both bots must have it in supported_games. See the opponent's games on the bots page. If either bot lacks the game, the reply is HTTP 409 with the error below.
{"action":"agent_challenge","target_id":2,"game_mode":"anti"}
{"action":"agent_challenge","target_name":"Opponent","game_mode":"grand"}HTTP 409
{"ok":false,"error":"unsupported game mode","server_now_ms":1800000000000}Changing supported_games
The registration form starts with Standard checked, and older bots without a saved list support std. You can change the list only in Manage on the bot web page, never with the bot token (API). The change is refused while a match is running or waiting for acceptance. An empty list cannot be saved.
Humans versus registered bots
People can challenge your bot in any game it has registered. If it supports standard, both STD and XOT can arrive. XOT arrives with game_mode std and starts from a board where 8 moves have already been played (they are included in history). The person who challenges chooses the clock, and the game is unrated. A human game has one leg (leg 0) and a negative match_id. The server handles passes when no move is possible, so do not send -1. Online registered bots with automatic matching enabled can also join supported STD/XOT quick matches. Quick matches are rated for members and unrated for guests.
Illegal moves and time
An illegal move or stale revision is rejected with HTTP 409 (illegal_move, stale_revision, not_your_turn) and the board does not change. The clock keeps running meanwhile. The connector resends the same move with the same revision, so unless the engine is fixed, that leg is eventually lost on time. The server has no per-move limit and only checks each color's remaining clock. The 10 seconds is the connector's default --max-think-seconds.
Match rules
All bot matches start from a random position containing 12 discs. Two games run simultaneously with colors reversed. Combined disc counts decide the winner; fewer discs win in Anti.
Every game type gives each bot 1 minute per board.
If a bot has not made its first move within 30 seconds of the start, the match is aborted and not rated. If one bot's connection is lost for more than 30 seconds during the match while the other is connected, the connected bot wins (finish_reason: disconnect) and the result is rated.
The server calculates the FlipSight bot's moves in every game type. Both web challenges and API challenges (agent_challenge) are accepted, and the server starts the match right away, so you do not need to keep the game room open. If the server calculation stops for more than 30 seconds, the match is aborted (finish_reason: technical) and not rated. Variant moves are expensive to calculate, so at most 2 variant matches against FlipSight bots run at once. When they are full you get HTTP 409 with site bot variant matches are full; try again shortly.
Auto matching pairs bots within 500 rating points in a game both have selected. The match starts when the connector accepts within 120 seconds and counts toward ratings. Registered bots can choose games or turn off auto matching under Manage. A bot started with the practice engine (environment.practice is true) is left out of automatic matches, and bot-vs-bot games it plays meanwhile are not rated.
A direct human challenge plays one game in a normal room with a supported game and clock; the server always makes direct challenges unrated. Online registered bots with automatic matching enabled can also join supported STD/XOT quick matches. Quick matches are rated for members and unrated for guests. A registered bot accepts only as many games as its simultaneous-games setting (default 2). One human game and one bot match (two boards) each count as 1.
Match flow
pending → running → finished / aborted
pending → rejected / expired
kind=human: id=-room_id, legs[0], round_no, room_created_at
agent_move: move=19 / "d3" / "D3" (8×8)
10×10: "j10" = "J0" = 99
pass: -1 / "pass" / "PA" / "PS" / "--" (paired games only)
index=row*board_size+column (0-based)All bot matches start from a random position containing 12 discs. Two games run simultaneously with colors reversed. Combined disc counts decide the winner; fewer discs win in Anti.
Your participant number is 0 if you are bot_a and 1 if you are bot_b. Participant 0 is black (1) in legs[0] and white (2) in legs[1]; participant 1 is the opposite. It is your turn when leg.status is active and leg.turn equals your color. It can be your turn in both legs at once.
If you have no legal move, you must send move -1 (pass) yourself; the server does not pass for you. In games against a person, the server handles passes as in normal game rooms.
On your turn, remaining time = clocks_ms[your color - 1] - (server_now_ms - turn_started_ms). clocks_ms is in color order (black, white); totals and winner are in participant order (winner 0 or 1, null for a draw).
Square numbers
Square number = row × 8 + column, so a1=0, h1=7, a2=8 and h8=63. For example, 19 is d3 and 37 is f5. The board array uses the same order, with 0=empty, 1=black, 2=white.
a b c d e f g h
1 0 1 2 3 4 5 6 7
2 8 9 10 11 12 13 14 15
3 16 17 18 19 20 21 22 23
4 24 25 26 27 28 29 30 31
5 32 33 34 35 36 37 38 39
6 40 41 42 43 44 45 46 47
7 48 49 50 51 52 53 54 55
8 56 57 58 59 60 61 62 63On 10×10 (grand, octagon), square = row × 10 + column. Columns are a to j, and the tenth row is written as 10 or 0 in coordinates. a1=0, j1=9, a2=10, j10=99 (same as j0). The same coordinate has a different number on each board size: d3 is 19 on 8×8 and 23 on 10×10.
a b c d e f g h i j
1 0 1 2 3 4 5 6 7 8 9
2 10 11 12 13 14 15 16 17 18 19
3 20 21 22 23 24 25 26 27 28 29
4 30 31 32 33 34 35 36 37 38 39
5 40 41 42 43 44 45 46 47 48 49
6 50 51 52 53 54 55 56 57 58 59
7 60 61 62 63 64 65 66 67 68 69
8 70 71 72 73 74 75 76 77 78 79
9 80 81 82 83 84 85 86 87 88 89
10 90 91 92 93 94 95 96 97 98 99Octagon (octagon)
a b c d e f g h i j
1 ## ## 2 3 4 5 6 7 ## ##
2 ## 11 12 13 14 15 16 17 18 ##
3 20 21 22 23 24 25 26 27 28 29
4 30 31 32 33 34 35 36 37 38 39
5 40 41 42 43 44 45 46 47 48 49
6 50 51 52 53 54 55 56 57 58 59
7 60 61 62 63 64 65 66 67 68 69
8 70 71 72 73 74 75 76 77 78 79
9 ## 81 82 83 84 85 86 87 88 ##
10 ## ## 92 93 94 95 96 97 ## ##Engine adapter
The FlipSight bot connector (Python 3.9+, standard library only) runs on Windows, macOS and Linux and connects an engine in two ways. --engine starts the engine once per game, sends one JSON line for every move and reads one {"move": square} line. An engine that answers one line and exits still works because it is started again on the next move, but an engine that reads input to the end (sys.stdin.read() and so on) never answers, so read one line at a time. legal_moves in the request lists the legal squares; if it is empty, answer -1. --nboard keeps an NBoard protocol engine running, one per leg; set its search depth with --nboard-depth.
API actions
Response examples show the format. The copy button copies only the request and does not call the API.
POST agent_environment
Report environment
Reports the CPU, OS, engine name, threads and practice flag of the connector PC. Send it at start and when the values change. The reply carries your bot.
| Parameters | Type | Required | Description |
|---|---|---|---|
action | string "agent_environment" | Required | Name of the action to call |
environment | object | Required | CPU, OS and engine name of the connector PC (up to 120 characters each, optional) and practice (true or false, optional). practice true means the bot is practising: it is left out of automatic matches, and bot-vs-bot games requested or accepted meanwhile are not rated. The connector sends this automatically when started with the practice engine. The server remembers the last value, so when practice is over, send it without practice or with false. hash_mb (MB): Per engine. Uses the connector value; enter manually if unavailable. ponder (true / false / null): Display only. If not reported, select manually. Change the actual setting in the engine. |
Request example
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_environment","environment":{"cpu":"Apple M4","engine":"MyEngine","os":"Darwin","engine_threads":1,"hash_mb":32,"ponder":false}}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_environment","environment":{"cpu":"Apple M4","engine":"MyEngine","os":"Darwin","engine_threads":1,"hash_mb":32,"ponder":false}}'Response example
{
"ok": true,
"bot": {
"id": 2,
"name": "MyBot",
"owner_id": "example",
"owner_name": "Example",
"owner": {
"player_id": "example",
"name": "Example",
"photo": "/img/no_profile.gif",
"country_code": "",
"country_name": "",
"country_flag_url": "",
"donor": false,
"verified_player_id": ""
},
"engine_level": null,
"rating": {
"rating": 1200,
"rd": 300,
"official": false,
"official_progress": {
"kind": "provisional",
"current": 0,
"required": 50
},
"color": "pz-rating-unofficial",
"high_rating": 1200,
"wins": 0,
"losses": 0,
"draws": 0,
"streak": 0,
"best_streak": 0
},
"supported_games": ["std", "anti"],
"auto_match": true,
"bio": "",
"registered_at": "2026-11-12 18:00:00",
"registered_at_ts": 1794474000,
"environment": {
"cpu": "Apple M4",
"engine": "MyEngine",
"os": "Darwin",
"practice": false,
"engine_threads": 1,
"hash_mb": 32,
"ponder": false
},
"env": {
"cpu": "Apple M4",
"engine_threads": 1,
"hash_mb": 32,
"hash_mb_reported": 32,
"hash_mb_override": null,
"ponder": false,
"ponder_reported": false,
"ponder_override": null,
"cpu_override": null,
"engine_threads_override": null,
"cpu_reported": "Apple M4",
"engine_threads_reported": 1
},
"is_builtin": false,
"online": true,
"disabled": false,
"deleted": false,
"photo": "/flipsight/bot_match_api.php?action=photo&bot_id=2&v=1794474000000"
},
"server_now_ms": 1800000000000
}POST agent_challenge
Challenge
Specify target_id (bot ID) or target_name (bot name), shown on the bots page. Built-in FlipSight bots (is_builtin: true) can be challenged through the API in every game type, and the server starts the match right away. When 2 variant matches against built-in bots are already open, you get HTTP 409 with site bot variant matches are full. If the target bot has turned off "Bot challenges" in bot management, you get HTTP 409 with bot does not accept bot challenges. Automatic bot matches ignore this setting and follow the auto matching setting.
You can challenge the same bot up to three times in a row. Wait five minutes after the third match ends.
| Parameters | Type | Required | Description |
|---|---|---|---|
action | string "agent_challenge" | Required | Name of the action to call |
target_id | integer ≥ 1 | Optional | ID of the bot to challenge |
target_name | string | Optional | Name of the bot to challenge (instead of target_id) |
game_mode | string std | anti | octagon | grand | reversi | Optional | Game for a bot pair. Defaults to std. Both bots must support it. Standard / Anti / Octagon / Grand (10x10) / Classic Reversi |
Request example
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_challenge","target_id":2,"game_mode":"anti"}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_challenge","target_id":2,"game_mode":"anti"}'Response example
{
"ok": true,
"match_id": 123,
"server_now_ms": 1800000000000
}POST agent_accept
Accept
| Parameters | Type | Required | Description |
|---|---|---|---|
action | string "agent_accept" | Required | Name of the action to call |
match_id | integer ≥ 1 | Required | Match ID (negative for games against a person) |
Request example
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_accept","match_id":123}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_accept","match_id":123}'Response example
{
"ok": true,
"match": {
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_reject
Decline
| Parameters | Type | Required | Description |
|---|---|---|---|
action | string "agent_reject" | Required | Name of the action to call |
match_id | integer ≥ 1 | Required | Match ID (negative for games against a person) |
Request example
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_reject","match_id":123}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_reject","match_id":123}'Response example
{
"ok": true,
"match": {
"id": 123,
"status": "rejected",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_move
Submit a move
| Parameters | Type | Required | Description |
|---|---|---|---|
action | string "agent_move" | Required | Name of the action to call |
match_id | integer ≠ 0 | Required | Match ID (negative for games against a person) |
round_no | integer ≥ 0 | Required against a person | Games against a person only: round_no from the match object |
room_created_at | string | Required against a person | Games against a person only: room_created_at from the match object |
leg | integer 0 | 1 | Required | Leg 0 or 1 (0 for games against a person) |
revision | integer ≥ 0 | Required | Revision of the leg your move was computed for; 409 stale_revision if the leg has changed |
move | integer -1..99 | string | Required | Square 0-(board_size²−1), -1 for a pass / d3 / D3 / pass |
eval | number -100..100 | Optional | Your engine's evaluation after this move, in discs from your side (+ means you are ahead, 2 decimals kept). It can go up to the number of playable squares: -64 to 64 on 8x8, -100 to 100 on 10x10 and -88 to 88 on octagon. If you leave it out or send a wrong value, only the eval is dropped and the move is accepted. Only bot matches keep it, and everyone sees it during the game, the opponent bot too, while games against people ignore it. |
Request example
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":123,"leg":1,"revision":0,"move":2,"eval":1.5}'Humans versus registered bots
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_move","match_id":-45,"leg":0,"revision":0,"move":"d3","round_no":1,"room_created_at":"2026-11-12 19:00:00"}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_move","match_id":-45,"leg":0,"revision":0,"move":"d3","round_no":1,"room_created_at":"2026-11-12 19:00:00"}'Response example
{
"ok": true,
"match": {
"id": 123,
"status": "running",
"bot_a": 1,
"bot_b": 2
},
"server_now_ms": 1800000000000
}POST agent_games
Download game records
Returns your bot's finished games as game records. The response is NDJSON (Content-Type application/x-ndjson), one game per line. It includes bot matches and games against people, but not training games or games against the house account othelloclub. Technical voids are included with result void.
This request does not mark your bot online and does not count toward the v2 spec check. Each bot may call it once every 5 seconds; a faster call gets 429 with retry_after_sec. Send Accept-Encoding: gzip to receive a compressed response.
| Parameters | Type | Required | Description |
|---|---|---|---|
action | string "agent_games" | Required | Name of the action to call |
since | integer ≥ 0 | Optional | Earliest updated_ms to include, in ms. Default 0. |
until | integer ≥ 0 | Optional | Latest updated_ms to include, in ms. Default: now. |
max | integer 1..300 | Optional | Most games per response, 1 to 300. Default 100. |
games | array | Optional | Games to include (std, anti, octagon, grand, reversi). Default: all. |
order | string asc | desc | Optional | asc: oldest first (default). desc: newest first. |
Request example
curl 'https://othelloclub.com/flipsight/bot_match_api.php' \
-H "Authorization: Bearer $FS_BOT_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"action":"agent_games","since":1799913600000,"max":100}'Windows PowerShell
Invoke-RestMethod -Method Post -Uri 'https://othelloclub.com/flipsight/bot_match_api.php' -Headers @{Authorization="Bearer $env:FS_BOT_TOKEN"} -ContentType 'application/json' -Body '{"action":"agent_games","since":1799913600000,"max":100}'Response example
{
"format": 1,
"kind": "bot",
"id": 123,
"url": "https://othelloclub.com/flipsight/lab?match_id=123",
"game_mode": "std",
"opening_mode": "random12",
"board_size": 8,
"time_limit_sec": 60,
"auto": true,
"ranked": true,
"rating_applied": true,
"status": "finished",
"finish_reason": "discs",
"result": "win",
"started_ms": 1799999962428,
"finished_ms": 1800000000000,
"updated_ms": 1800000000000,
"me": {
"bot_id": 2,
"name": "MyBot",
"engine": "MyEngine",
"rating_before": 2138.51,
"rating_after": 2143.53
},
"opponent": {
"kind": "bot",
"bot_id": 9,
"name": "Ethan",
"builtin": true,
"engine": null,
"rating_before": 2017.41,
"rating_after": 2017.41
},
"discs": [73, 55],
"opening": "e6f6d3e7f5e3f7c4",
"opening_squares": [44, 45, 19, 52, 37, 20, 53, 26],
"opening_colors": "BWBWBWBW",
"legs": [
{
"my_color": "W",
"status": "finished",
"discs": [28, 36],
"result_discs": [28, 36],
"colors": "BWB",
"moves": "f3f4c3",
"squares": [21, 29, 18],
"at_ms": [1799999962491, 1799999965034, 1799999965089],
"used_ms": [63, 1111, 55],
"left_ms": [59937, 58889, 59882],
"evals": [null, -1.5, null]
},
{
"my_color": "B",
"status": "finished",
"discs": [37, 27],
"result_discs": [37, 27],
"colors": "BWB",
"moves": "b3b4c3",
"squares": [17, 25, 18],
"at_ms": [1799999963923, 1799999964158, 1799999965481],
"used_ms": [1495, 235, 1323],
"left_ms": [58505, 59765, 57182]
}
]
}Game records
A game record (record) is one JSON object for one finished game. It holds the players, result, ratings, opening and the time of every move, from your bot's side. You get the same object in two places.
- Finished game event: When a game ends, the last match event (status finished or aborted) carries record.
- agent_games: Returns finished games, one per line. Use it for past games and games you missed.
Moves use the site's game notation. Each move is two characters, and a pass is pa. Columns are a to j and rows 1 to 9; on 10×10 the tenth row is 0 (j0 is square 99). squares gives the same moves as square numbers (-1 for a pass), and colors gives the side that moved, B or W.
Games that end while your stream is down, and games against people whose record is not ready yet, bring no record in a finished game event. Fill such gaps with agent_games as follows.
- Where to start: Send the updated_ms of your newest saved record as since. since is inclusive, so your last record comes again.
- Skip duplicates: Skip a record whose kind and id you already have.
- Next page: Call again with the newest updated_ms you received. Stop when a response brings no new records.
- Changed records: A game that changes after it ended, such as a technical void, comes again with a newer updated_ms. Replace the old record with it.
Game record fields
| Field | Type | Description |
|---|---|---|
format | integer | Record format version, now 1. New fields may be added to version 1; the number goes up only when an existing field changes meaning. |
kind | string | bot: a bot match with two legs. human: a game against a person with one leg. |
id | integer | The bot match ID for kind bot, the game ID for kind human. kind and id together identify a record. |
url | string | Page to replay the game |
room_id, round_no | integer | null | Games against a person only: room and round |
game_mode | string | Game (std, anti, grand, octagon, reversi) |
opening_mode | string | random12: the random 12-disc start of a bot match. xot or std: how a game against a person started. |
board_size | integer 8 | 10 | Squares per side, 8 or 10 |
time_limit_sec | integer | Seconds given per leg, per color |
auto | boolean | Created by automatic matching |
ranked | boolean | Whether the match is rated |
rating_applied | boolean | Whether the result changed ratings |
status | string | finished, or aborted for a technical void |
finish_reason | string | null | Why the game ended: the same values as state.finish_reason for bot matches, the game room's value for games against a person. |
result | string | win, loss, draw or void, from your bot's side |
started_ms, finished_ms, updated_ms | integer | null | Start and end time in ms; started_ms is null for games against a person. updated_ms is when the record last changed, usually the end time, and since and until compare with it. |
me | object | Your bot: bot_id, name, engine, rating_before, rating_after. engine is the engine name reported at the start; both ratings are null when the game was not rated. |
opponent | object | Opponent: kind (bot, human or guest), name, engine, rating_before, rating_after. A bot also has bot_id and builtin, a person player_id. |
discs | [integer, integer] | Score of your bot and the opponent: the total of both legs (state.totals) for bot matches, disc counts for games against a person. |
opening, opening_squares, opening_colors | string, integer[], string | Opening moves before the legs, in the same notation: the random 12-disc start or the XOT opening. |
legs[].my_color | string | Your bot's color in this leg, B or W |
legs[].status | string | active, finished, timeout, stopped |
legs[].discs | [integer, integer] | Disc counts in color order (black, white) |
legs[].result_discs | [integer, integer] (optional) | Optional adjudicated score [black, white] for a leg lost on time; total it instead of discs. Scores for the side that timed out and its opponent: std and reversi 0 to 64, grand 0 to 100, octagon 0 to 88, anti 64 to 0. The other leg continues, and the totals decide the winner after both legs end. Older finished records are not recalculated. |
legs[].moves, squares, colors | string, integer[], string | The leg's moves after the opening: moves as a string, squares as numbers, colors as B or W for each move. |
legs[].at_ms, used_ms, left_ms | (integer | null)[] | For each move: when it was played in ms, the time used, and the mover's remaining clock after it. Play times are null in games against people, and unknown values are null. |
legs[].evals | (number | null)[] (optional) | The eval each mover sent with its move, in discs from that mover's side. Moves sent without one have null. The field is left out when no move in the leg had one. |
Errors
Errors look like {"ok": false, "error": "…"}. On 401, stop and check the token. On 409, check the turn, revision and legal moves in your latest state (reconnect the stream if you are unsure). 410 means the action was removed (agent_poll from 2026-11-22 00:00 (UTC+9)): use the event stream. 429 means too many requests (over 20 per second from one bot, or 40 per second from all bots on one IP address, to bot_match_api.php). On 429, 5xx and connection errors, send the same request again after 0.2 to 0.5 s (follow Retry-After when present) and lengthen the delay after a few tries. Never resend an illegal move.
{"ok":false,"error":"stale_revision","server_now_ms":1800000000000}| HTTP | error |
|---|---|
| 400 | JSON object required / unknown action |
| 401 | invalid bot credential |
| 403 | access denied / invalid csrf |
| 405 | POST required |
| 409 | stale_revision / not_your_turn / illegal_move / leg_finished / match not running / match timed out / stale room revision / invalid move coordinate / move outside board / unsupported game mode / both bots must be connected / bot already has an active match / bot busy / engine thread limit exceeded / bot challenge repeat limit / challenge expired or answered / site bot variant matches are full / target bot not found |
| 410 | agent_poll was removed; use bot-stream |
| 413 | request too large |
| 429 | Too many requests (bot_match_api.php rate limit) |
| 503 | bot match storage unavailable |
agent_poll
Read state (removed on 2026-11-22)
Removed on 2026-11-22 00:00 (UTC+9; 2026-11-21 15:00 UTC): from then on it returns HTTP 410 {"ok": false, "error": "agent_poll was removed; use bot-stream"}. Use the event stream for your state and reconnect it to resync. Until then it still answers, but from 2026-11-21 23:40 (UTC+9) a registered bot that called it in the last 10 minutes is left out of automatic matching.
Implementing the API yourself