Player History API

This document outlines the reverse-engineered specification for fetching a player’s game history from the external Dice Chess API (https://dicechess.com). Since official documentation is unavailable, this reference is based on observed network requests and payloads.

Endpoint

POST /api/player/history
Content-Type: application/json
Authorization: Bearer <token>

Note

Authentication is required. A valid Bearer token must be provided in the headers.

---

Request Payload

The request body is a JSON object used to filter, sort, and paginate the game history of a given player.

Example Request

{
    "filters": {
        "PLAYER_ID": "303082",
        "START_DATE": "1773957600000",
        "END_DATE": "1774043999999",
        "COLOR": "WHITE",
        "ALLOW_DOUBLING": "false"
    },
    "startBets": [10, 25, 100],
    "allowedTimes": [61, 120, 180, 305],
    "pageSize": 50,
    "first": 0,
    "sortColumn": "DATE",
    "isAsc": false
}

Field Definitions

Field	Type	Description
filters	Object	Key-value pairs for basic database filtering.
filters.PLAYER_ID	String	Required. The internal user ID of the player whose history is being fetched.
filters.START_DATE	String	Unix timestamp (in milliseconds) as a string.
filters.END_DATE	String	Unix timestamp (in milliseconds) as a string.
filters.COLOR	String	(Optional) Filter by piece color: "WHITE" or "BLACK".
filters.ALLOW_DOUBLING	String	(Optional) Filter by game mode: "true" for X2 mode, "false" for Classic mode.
startBets	Number[]	Array of requested coin bets (e.g., [10, 25, 100]). Leave empty [] to allow all bets.
allowedTimes	Number[]	Array of specific Time Controls to filter by. Leave empty [] to allow all time limits.
pageSize	Number	Number of records to return per page.
first	Number	Pagination offset (skip the first N records).
sortColumn	String	Column to sort by. E.g., "DATE".
isAsc	Boolean	Sort direction (true for Ascending, false for Descending).

Unpacking allowedTimes

The values stored in the allowedTimes array are encoded utilizing the following logic: Base time in seconds + Increment in seconds.

For example:

• 1m + 1s → 60 + 1 = 61
• 2m → 120 + 0 = 120
• 3m → 180 + 0 = 180
• 3m + 3s → 180 + 3 = 183
• 5m → 300 + 0 = 300
• 5m + 5s → 300 + 5 = 305

---

Response Schema

The API returns a paginated list of game metadata objects. Each object provides extensive details about the match, opponent, rating delta, and result.

Example Game Object (Meta)

{
  "historyOpponent": {
    "opponentId": 782580,
    "opponentName": "NKNK",
    "opponentAvatar": "stuffPack_2",
    "userOnlineStatus": "OFFLINE"
  },
  "timeLimit": 5,
  "timeBonus": 5,
  "allowDoubling": true,
  "moneyDelta": 600.0,
  "currency": "GOLD",
  "color": "WHITE",
  "startTime": "2026-03-30T20:08:44.793",
  "timeSpent": 91,
  "gameId": "28576336-2c74-11f1-aff2-97f136c9a99a",
  "fenUsed": false,
  "ratingChangeWhite": 0.0,
  "ratingChangeBlack": -0.0,
  "startRatingWhite": 3574.64,
  "startRatingBlack": 2633.27,
  "result": 1,
  "isCancelled": false
}

Field Definitions

Field	Type	Description
historyOpponent	Object	Details of the opponent, including ID, Name, Avatar, and Online Status.
timeLimit	Number	The base time constraint for the game, given in minutes.
timeBonus	Number	The time increment applied per move, given in seconds.
allowDoubling	Boolean	true if the game was X2 mode. false if Classic mode.
moneyDelta	Number	The amount of coins won/lost during the game.
currency	String	The currency used. Always "GOLD" for regular wagers.
color	String	The color pieces the queried player controlled ("WHITE" or "BLACK").
startTime	String	ISO-8601 formatted datetime of when the game started.
timeSpent	Number	Total play time, likely in total seconds spent in-game.
gameId	String	UUID string representing the unique game match.
ratingChange[Color]	Number	Delta change applied to the players’ Elo ratings post-game.
startRating[Color]	Number	The starting rating of the White and Black players.
result	Number	The outcome of the game relative to the queried player: 1 = Win, 0 = Draw, -1 = Loss.
isCancelled	Boolean	Indicates if the game was aborted/cancelled before completion.