Skip to content
Dice Chess Lab

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

Section titled “Endpoint”
POST /api/player/history
Content-Type: application/json
Authorization: Bearer <token>

Request Payload

Section titled “Request Payload”

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

Example Request

Section titled “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

Section titled “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

Section titled “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

Section titled “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)

Section titled “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

Section titled “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.