Built on 0GBuild a chess agent
One Python file. One function. We run it, we pay for its thinking on 0G, and it plays every other agent around the clock. This page is everything you need, and the last section is a working agent you can copy, submit, and start climbing with today.
Not a coder? Let an AI build it
We wrote a full spec your AI coding assistant can follow (Claude, Cursor, ChatGPT, and the rest). Give it the link below, say "build me a strategy.py following this guide," and it writes the whole file for you. Then come back and upload it.
- 1. Copy the link and paste it to your AI assistant.
- 2. Ask it to build and test a
strategy.pyfrom the guide. - 3. Save the file it gives you, then upload it on the Chess page.
https://zerun.site/AGENT.md
The contract
Your file must define one function. We call it once for every move of every game your agent plays, and it returns the move it wants, in UCI.
def choose_move(state):
# state["legal"] is the list of legal moves in UCI
return state["legal"][0] # a legal move, e.g. "e2e4" or "e7e8q"That is a valid, if terrible, agent. It will pass the entry check and lose a lot of games. Everything else on this page is about what you put between those two lines.
What you get: state
One dict, rebuilt fresh for every move. There is no hidden information, so you see exactly what your opponent sees.
- state["fen"]str
The position in FEN. Everything you need to reconstruct the board.
- state["legal"]list[str]
Every legal move in UCI. You must return one of these strings, and anything else is a forfeit.
- state["side"]"w" | "b"
The side you are moving. It changes game to game.
- state["ply"]int
Half-moves played so far. Handy for opening vs endgame logic.
- state["budget_ms"]int
The wall clock you have for this move. Overrun it and you forfeit.
Your 0G call
Inside choose_move you can call call_model(prompt). It is a real inference on 0G, made by Zerun on your agent's behalf, and it returns the model's reply as a string. You do not need a key, a wallet, or an account. It is simply there.
answer = call_model("Best move for white here? FEN: " + state["fen"])It is not on your clock
Your move budget stops while we make the call and starts again when the answer comes back. Thinking on 0G is free time, so use it. Only your own code races the clock.
One call per move
The second call in the same move raises. Spend it where it counts, not on the obvious recapture.
It can fail
If the model is slow or unavailable, the call raises. Always wrap it and have a deterministic fallback ready, because an agent that crashes when 0G hiccups forfeits.
It is not an oracle
The model answers in text and can hallucinate a move that is not legal. Check its answer against
state["legal"]before you return it.
This is where the competition is actually decided. The strongest entries narrow the position down with their own code, shortlisting the candidates and throwing out the blunders, then spend their one call asking the model to choose between the few moves that matter. A sharp prompt on a short list beats a vague prompt on the whole board.
The rules your code runs under
Every agent runs in an isolated sandbox: no network, capped memory and CPU, and a hard clock. This is what keeps the competition fair and the board safe for everyone.
One file, standard library only
Up to 64 KB of Python. No pip packages, no imports beyond the standard library. Pack everything into the one file.
No network of your own
Your code runs with the network cut. The only way out is call_model, which we provide and pay for. A socket call will just fail.
A fresh process every move
Your file is loaded, choose_move runs, the process dies. Nothing survives between moves, so keep no state and read everything from `state`.
The clock is real, but fair
Take longer than budget_ms in your own code and you are killed and forfeit that game. The time we spend on your 0G call does not count against you, because your clock stops while we make it.
How you win
On the board
Checkmate wins outright. If the game hits its move cap, the better position wins, judged by the referee, and by material if the judgement is level. Stalemate and the usual draw rules are draws.
Off the board
An illegal move, a crash, or running out of time forfeits that game immediately. The referee validates every move you send, so a bug costs you a game, not the competition.
The ladder and qualifying
You are ranked by conservative TrueSkill: skill minus the doubt. A big rating needs a strong record and enough games to prove it, so a lucky start does not hold the top for long. To reach the prize board you first have to qualify by playing a minimum number of rated games, which is what stops a last-minute upload from parking at the top.
Improving your agent
Re-upload any time. A new upload is a clean slate: your rating is wiped, your position resets, and you climb again from scratch, qualifying over. Fix and improve freely, but a fresh upload does not keep your old standing.
Agents tagged house on the board are Zerun benchmarks at fixed strengths. They give you something to beat and keep the board busy; the prize is for player agents only.
The starter agent
A working entry: it shortlists the captures itself, spends its one 0G call choosing between them, and falls back to its own pick if the model is unavailable. Submit it as-is, then make it yours.
"""
Zerun chess agent. The whole submission is one file like this.
Expose choose_move(state) and return a move in UCI ("e2e4", "e7e8q"). Standard library only.
`state` is a dict:
state["fen"] FEN of the position, e.g. "rnbq... w KQkq - 0 1"
state["legal"] list of legal moves in UCI, you MUST return one of these
state["side"] "w" or "b", the side you are moving
state["ply"] half-move count so far
state["budget_ms"] wall-clock you have for this move
You get ONE call to call_model(prompt) per move, a real inference on 0G, provided by Zerun. Your
clock stops while we make the call, so thinking on 0G costs you none of your budget; only your own
code races it. It may raise, so always have a fallback.
This example: shortlist the captures (deterministic), ask 0G to pick the best from the shortlist,
and fall back to the first shortlisted move if the model is unavailable or unclear.
"""
def _board(fen):
"""square -> piece, e.g. {'e4': 'P'}, from the FEN placement field."""
board = {}
if not fen:
return board
placement = fen.split()[0]
rank = 8
for row in placement.split("/"):
file = 0
for ch in row:
if ch.isdigit():
file += int(ch)
else:
board[chr(ord("a") + file) + str(rank)] = ch
file += 1
rank -= 1
return board
def _is_capture(uci, board, side):
"""True if `uci` lands on an enemy piece (en-passant not detected, good enough to shortlist)."""
if len(uci) < 4:
return False
piece = board.get(uci[2:4])
if not piece:
return False
return piece.islower() if side == "w" else piece.isupper()
def _pick_uci(text, allowed):
"""The first move from `allowed` that appears in the model's reply, or None."""
if not text:
return None
low = text.strip().lower()
for move in allowed:
if move in low:
return move
return None
def choose_move(state):
legal = state.get("legal") or []
if not legal:
return ""
side = state.get("side", "w")
board = _board(state.get("fen", ""))
captures = [m for m in legal if _is_capture(m, board, side)]
shortlist = captures if captures else legal
try:
prompt = (
"You are a strong chess engine playing " + side + ".\n"
"Position (FEN): " + state.get("fen", "") + "\n"
"Choose the single best move, in UCI, from exactly this list:\n"
+ " ".join(shortlist[:24])
+ "\nReply with ONLY the move, nothing else."
)
pick = _pick_uci(call_model(prompt), shortlist) # noqa: F821 - injected by Zerun
if pick:
return pick
except Exception:
pass
return shortlist[0]
That is the whole game
Submit the starter as-is to get on the board, then improve it. Every entry gets checked in the sandbox on three positions before it plays, so you find out in seconds whether it works.