Chastity Tracker API v2 Documentation: Games (DICE / LUCK / LINK)

🔐 Authentication

Depending on the game mode, requests may be public or require authentication via HTTPS bearer token.

Rules

• DICE: bearer token required.
• LUCK: bearer token required.
• LINK dom=1 (dom play): bearer token required.
• LINK dom=0 (public vote): bearer token not required (optional).

Usage

URL

https://www.chastitytracker.org

HEADER (Authenticated example)

POST /api/v2/games.php HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

HEADER (Public LINK vote example)

POST /api/v2/games.php HTTP/2
Host: www.chastitytracker.org
Content-Type: application/json

📦 Response Envelope

All v2 endpoints return a unified JSON envelope.

Success

{
  "ok": true,
  "data": { ... },
  "meta": {"version":2}
}

Error

{
  "ok": false,
  "error": {"code":"...", "message":"..."},
  "meta": {"version":2}
}

ℹ️ About Games

Games modify a session’s scheduledend and generate a new entry in histories. Supported games are: DICE, LUCK, LINK.

Common Output Fields

• session: session id
• dom: 0/1 (1 means performed by a dom)
• operation: ADD | SUB
• seconds: seconds added or subrtracted
• scheduledend_utc: new UTC scheduled end after the operation
• multiplier: random multiplier

Security

• DICE/LUCK are always private and require bearer token.
• LINK can be public (dom=0) if the user enabled the LINK game and shares the token link.

📌 Endpoint: POST /api/v2/games.php

Plays a game action and updates the session schedule.

Request Body (JSON)

{
  "game": "dice" | "luck" | "link",
  "dom": 0 | 1,
  "session": 123,
  "token": "PUBLIC_LINK_TOKEN",
  "type": "add" | "sub" | "rand"
}

Fields

• game: required. Allowed: dice, luck, link.
• dom: required. 0 = owner/public, 1 = dom action.
• session: required for DICE, LUCK, and LINK dom=1. Optional for LINK dom=0 if token is provided (session is resolved by token).
• token: required for LINK dom=0 (public vote). Optional elsewhere.
• type: required for LINK (both dom modes). Allowed: add, sub, rand.

Permission Rules

• DICE/LUCK:
  • dom=0: bearer token user must be the session owner.
  • dom=1: bearer token user must be the dom of the owner (active link required).
• LINK:
  • dom=1: bearer token required, must be dom of the owner.
  • dom=0: public vote, no bearer required. If bearer is present, it is used to identify the voter.

⚠️ Penalty (Immediate)

For LINK dom=0, if the request includes a bearer token belonging to the session owner, the API triggers a penalty immediately:

• penalty = 1
• type is forced to add
• multiplier is forced to maxmultiplier
• history source becomes PENALTY

LINK Vote Cooldown (dom=0)

Votes are limited according to LINK configuration:

• waitint=0: vote once ever.
• waitint=1: vote again after 24 hours.

Vote Uniqueness

• Logged voter (bearer present): uniqueness is by (token, session, user) only (IP is ignored).
• Anonymous voter (no bearer): uniqueness is by (token, session, ip) where user IS NULL.

Example Requests

1) Public LINK vote (anonymous)

POST /api/v2/games.php HTTP/2
Host: www.chastitytracker.org
Content-Type: application/json

{
  "game":"link",
  "dom":0,
  "token":"AbCdEf123...",
  "type":"rand"
}

2) Public LINK vote (logged)

POST /api/v2/games.php HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "game":"link",
  "dom":0,
  "token":"AbCdEf123...",
  "type":"add"
}

3) DICE (owner)

POST /api/v2/games.php HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "game":"dice",
  "dom":0,
  "session":123
}

4) LUCK (dom)

POST /api/v2/games.php HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "game":"luck",
  "dom":1,
  "session":123
}

Response Examples

LINK

{
  "ok": true,
  "data": {
    "game":"link",
    "operation":"ADD",
    "multiplier":1.37,
    "time":3600,
    "unit":"hour",
    "int":1,
    "seconds":3600,
    "dom":0,
    "scheduledend_utc":"2026-02-10 00:00:00",
    "session":123,
    "penalty":null
  },
  "meta":{"version":2}
}

DICE

{
  "ok": true,
  "data": {
    "game":"dice",
    "operation":"SUB",
    "time":7200,
    "sum":-3,
    "dices":[6,1,2],
    "dicesops":["","s",""],
    "calc":"+6-1+2",
    "multiplier":1.11,
    "seconds":7200,
    "dom":0,
    "scheduledend_utc":"2026-02-10 00:00:00",
    "session":123
  },
  "meta":{"version":2}
}

LUCK

{
  "ok": true,
  "data": {
    "game":"luck",
    "operation":"ADD",
    "time":86400,
    "int":1,
    "multiplier":1.22,
    "seconds":86400,
    "dom":1,
    "scheduledend_utc":"2026-02-11 00:00:00",
    "session":123
  },
  "meta":{"version":2}
}

Status Codes

• 200 OK — Played successfully
• 400 Bad Request — Validation error (missing fields, cooldown, etc.)
• 401 Unauthorized — Missing/invalid token (where required)
• 403 Forbidden — Permission denied (not owner / not dom)
• 404 Not Found — Link token or session not found
• 405 Method Not Allowed — Not POST
• 500 Internal Server Error — Server error

⚠️ Notes

• All timestamps returned by this endpoint are UTC.
• The endpoint inserts a row in histories for each game action.
• For LINK dom=0 (public vote): the API records voters and updates games.used/games.lastuse.
• For penalty: voters are not recorded and LINK game counters are not updated.

⚠️ Security Notes

• Tokens must be stored securely by third parties.
• Users can revoke or regenerate tokens at any time.
• Never share a user’s token or sensitive info.

📅 Changelog

• 2026-02-14: initial v2 release

To go back to documentation index click here.