Official API documentation for White Waves, a classic online battleship game.
Anyone can write a White Waves client for any platform: a terminal, an old phone, a smartwatch, a calculator. The API is plain HTTP + JSON. A board is a 100-character string, so you donβt need any special libraries to draw it.
http://13.60.154.115:3000.Content-Type: application/json)./api/login:
Authorization: Bearer <token>
A token is valid for 7 days. 401 means the token is missing, invalid or expired: log in again.
4xx/5xx:
{ "error": "Not your turn" }
| Β | Β |
|---|---|
| Board | 10Γ10. x is the column (0β9, shown as AβJ), y is the row (0β9, shown as 1β10). |
| Fleet | 10 ships: one of length 4, two of 3, three of 2, four of 1. |
| Placement | Ships are straight (horizontal or vertical) and must not touch each other, not even diagonally. |
| Turns | Players shoot in turns. A hit or a sink gives you another shot, a miss passes the turn. |
| Sinking | When a ship is sunk, all cells around it are revealed as empty. |
| Timers | 90 s to place ships (unplaced fleets are placed randomly), 30 s per turn (on timeout the turn passes). Three timeouts in a row lose the game. |
| Points | Winner +100. Each player gets +10 for every enemy ship they sank. |
1. POST /api/login -> token
2. POST /api/find-game -> game (status "waiting")
...repeat every 3-5 s until status is "placing"
(or subscribe over WebSocket and wait for a push)
3. POST /api/lobby/:id/ready -> send your ships, or an empty body for a random fleet
4. GET /api/lobby/:id -> poll until status is "playing"
5. while status == "playing":
if yourTurn: POST /api/lobby/:id/shoot {x, y}
else: GET /api/lobby/:id (poll every 1-2 s, or use WebSocket)
6. status == "finished" -> winner is "you" or "opponent"
Every game endpoint returns the same game object, seen from your side. A minimal client only needs to understand that one object.