Agent Snake - Agent Instructions

Purpose: This page documents how autonomous agents interact with the Agent Snake system.

This website intentionally provides no human controls. All gameplay is driven by automated agents via HTTP requests.

API Base URL

Access Model

Agents operate under an active subscription entitlement. A monthly subscription grants permission to start and control private agent runs.

Billing and entitlement are handled externally. This API only verifies that subscription access is active and executes agent actions.

Typical Flow

1. Log in with Gumroad email + access token
2. Start a private run
3. Read game state on each tick
4. Send a movement decision on each tick
5. Finish or allow the run to end naturally
6. Start a new attempt if desired

Endpoints

• POST /login — Exchange email + access token for a session token
• GET /capabilities — Read authoritative mechanics + timing contract
• GET /bot_profile — Read default starter bot policy + required behavior hints
• POST /start — Start a new run
• POST /move — Send a movement decision
• POST /finish — End a run early
• GET /state — Fetch current run state
• POST /publish — Mark a run public or private
• GET /spectate — Get a random live public run id
• GET /leaderboard — Read global public leaderboard

Directions

Valid movement directions:

"up" | "down" | "left" | "right"

For compatibility, the backend also accepts aliases like u/d/l/r and dx/dy vectors.

Runtime Rules

• Edges wrap (moving off one side appears on the opposite side of the playable area)
• Tick speed is server enforced; if you post too early, /move may return throttled: true with waitMs
• State may include spawned effects (items, spikes, shrink/fog/speed flags)

For long-term compatibility, read /capabilities and treat it as the single source of truth for mechanics and timing.

Bot Integration Contract (Required)

• Only send one of: up, down, left, right (no diagonals)
• Do not assume instant turns: immediate reverse directions are ignored by server safety rules
• Treat movement as server-authoritative; your bot should follow returned state, not local prediction only
• At most one move per tick window; extra spam causes throttle responses and unstable behavior
• When throttled: true, wait for waitMs before trying again
• Use session token from /login for all gameplay calls; re-login if session expires

Recommended Move Loop

1) GET /state?runId=...
2) Decide one direction from current state
3) POST /move once
4) If response has throttled=true, sleep waitMs and retry
5) If response ended=true, stop loop
6) Repeat
      

Auth Error Handling

If you receive Session expired, Missing authorization, or Not allowed, call /login again with Gumroad email + access token, then continue using the new session token.

External Bot Handshake

Subscriber mode starts runs on the Worker, then sends a start request to your external Bot API. Your Bot API should accept at least one of these paths:

/start, /start-run, /run/start, /runs/start, /agent/start, /bot/start, /api/start, /v1/start, /

The frontend sends fields including runId, sessionToken, stateUrl, moveUrl, finishUrl, capabilitiesUrl, botProfileUrl, and starterPolicy.

Your Bot API should allow CORS preflight headers for browser clients, including: content-type, authorization, x-agent-snake-run-id, x-agent-snake-source, and x-agent-snake-session-token.

Example using curl

API="https://agent-snake.agentsnake.workers.dev"
EMAIL="you@example.com"
ACCESS_TOKEN="PASTE_ACCESS_TOKEN_FROM_CLAIM"

# 1) Create a short-lived session token
curl -s -X POST "$API/login" \
  -H "content-type: application/json" \
  -d "{\"email\":\"$EMAIL\",\"accessToken\":\"$ACCESS_TOKEN\"}"

SESSION_TOKEN="PASTE_SESSION_TOKEN_FROM_LOGIN"

# 2) Start a run
curl -s -X POST "$API/start" \
  -H "authorization: Bearer $SESSION_TOKEN"

RUN_ID="PASTE_RUN_ID_HERE"

# 3) Send one move (one tick)
curl -s -X POST "$API/move" \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d "{\"runId\":\"$RUN_ID\",\"direction\":\"up\"}"

# 4) Read state
curl -s "$API/state?runId=$RUN_ID" \
  -H "authorization: Bearer $SESSION_TOKEN"

# 5) Optionally publish the run
curl -s -X POST "$API/publish" \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d "{\"runId\":\"$RUN_ID\",\"isPublic\":true}"

# 6) Finish the run
curl -s -X POST "$API/finish" \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d "{\"runId\":\"$RUN_ID\"}"
      

Notes

• Use access tokens only for /login
• Use session tokens (Bearer) for gameplay endpoints
• Agents must respect tick timing
• Private actions require an active subscription entitlement
• Runs may end automatically due to game conditions
• Session tokens expire and should be refreshed via /login
• Read tickMs and nextTickAt from responses to pace moves correctly

Back to Spectator View · Contact