> ## Documentation Index
> Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate bulk game data

> Generates N complete pre-calculated game states — each containing all 4 stages
(HOLE, FLOP, TURN, RIVER) with odds already computed for every hand.

This is the REST replacement for the legacy C# SOAP method
`f_get_bulk_gamestate_list` (hedgeem_asp_webservice). The JS client's static
`coreData[]` and `three_handed_game_data[]` arrays in `coredata.js` were
originally generated by that SOAP endpoint — this endpoint replaces it.

**Pipeline per game** (mirrors `HedgeEmTable.f_shuffle_deal_and_calculate_odds`):
1. Shuffle deck and deal hole cards + board cards
2. Calculate pre-flop odds (Monte Carlo)
3. Calculate flop odds (Monte Carlo)
4. Calculate turn odds (Monte Carlo)
5. Deterministic river evaluation
6. Apply house margin chain to each stage
7. Determine status flags (winner, favourite, cant-lose, best-rtp)
8. Populate best-five-cards and hand descriptions (flop onwards)

**Limits:** `numberOfGames` is capped at 200 per request.
For 50 games of 3 hands the response is ~300 KB.




## OpenAPI

````yaml /openapi.yaml post /api/games/bulk
openapi: 3.0.0
info:
  title: Texas Hedge'Em API
  version: 0.4.0
  description: >
    REST API for Texas Hedge'Em v5 — a player-vs-house poker odds game.


    Players place bets on the odds of multiple simultaneous poker hands

    at three betting stages: **Hole**, **Flop**, and **Turn**.

    The River card determines the winning hand and pays out winners.


    **Base URL:** `https://hedgeem-server.qeetoto.com`


    **Authentication:** All endpoints except `/api/health` and `GET /api/tables`

    require a Supabase JWT passed as a Bearer token in the `Authorization`
    header.

    See [Authentication](/authentication) for details.


    **Two-balance wallet model:** Every player has two separate balances:

    `accountBalance` (funds in their lobby wallet) and `seatBalance` (chips on
    the

    felt at a specific table). Sit deducts from account; Leave credits seat back
    to

    account; Top-up transfers account → seat during a session.
  contact:
    url: https://github.com/texashedgeem/hedgeem-v5
  license:
    name: MIT
servers:
  - url: https://hedgeem-server.qeetoto.com
    description: Production (Vercel)
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
paths:
  /api/games/bulk:
    post:
      tags:
        - Game
      summary: Generate bulk game data
      description: >
        Generates N complete pre-calculated game states — each containing all 4
        stages

        (HOLE, FLOP, TURN, RIVER) with odds already computed for every hand.


        This is the REST replacement for the legacy C# SOAP method

        `f_get_bulk_gamestate_list` (hedgeem_asp_webservice). The JS client's
        static

        `coreData[]` and `three_handed_game_data[]` arrays in `coredata.js` were

        originally generated by that SOAP endpoint — this endpoint replaces it.


        **Pipeline per game** (mirrors
        `HedgeEmTable.f_shuffle_deal_and_calculate_odds`):

        1. Shuffle deck and deal hole cards + board cards

        2. Calculate pre-flop odds (Monte Carlo)

        3. Calculate flop odds (Monte Carlo)

        4. Calculate turn odds (Monte Carlo)

        5. Deterministic river evaluation

        6. Apply house margin chain to each stage

        7. Determine status flags (winner, favourite, cant-lose, best-rtp)

        8. Populate best-five-cards and hand descriptions (flop onwards)


        **Limits:** `numberOfGames` is capped at 200 per request.

        For 50 games of 3 hands the response is ~300 KB.
      operationId: generateBulkGames
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkGamesRequest'
            example:
              numberOfGames: 10
              numberOfHands: 3
              targetRtp: 0.97
      responses:
        '200':
          description: Pre-calculated game states
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkGamesResponse'
              example:
                numberOfGames: 1
                numberOfHands: 3
                targetRtp: 0.97
                generatedAt: '2026-03-24T12:00:00.000Z'
                games:
                  - gameId: BULK-0001
                    numberOfHands: 3
                    numberOfBettingStages: 3
                    hands:
                      - AcKd
                      - QsJs
                      - 8h7c
                    bc1: Ah
                    bc2: 3s
                    bc3: 9d
                    bc4: 2c
                    bc5: Kh
                    handStageInfoList:
                      - handIndex: 0
                        bettingStage: 0
                        percentWin: 62.4
                        percentDraw: 2.1
                        percentWinOrDraw: 64.5
                        oddsActual: 1.55
                        oddsMargin: 1.5
                        oddsRounded: 1.5
                        actualRtp: 0.968
                        roundingRake: 0
                        statusIsWinner: false
                        statusCantLose: false
                        statusIsFavourite: true
                        statusBestRtp: false
                        bestFiveCards: null
                        handDescShort: null
                        handDescLong: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    BulkGamesRequest:
      type: object
      properties:
        numberOfGames:
          type: integer
          description: How many games to generate (1–200, default 50)
          minimum: 1
          maximum: 200
          default: 50
          example: 10
        numberOfHands:
          type: integer
          description: Hands per game — 3 or 4 (default 3)
          enum:
            - 3
            - 4
          default: 3
          example: 3
        targetRtp:
          type: number
          description: House RTP target — must be > 0 and < 1 exclusive (default 0.97)
          minimum: 0
          exclusiveMinimum: true
          maximum: 1
          exclusiveMaximum: true
          default: 0.97
          example: 0.97
    BulkGamesResponse:
      type: object
      properties:
        games:
          type: array
          description: Pre-calculated game states, one per requested game
          items:
            $ref: '#/components/schemas/BulkGameState'
        numberOfGames:
          type: integer
          description: Actual count of games returned
          example: 10
        numberOfHands:
          type: integer
          description: Hands per game (echoed from request)
          example: 3
        targetRtp:
          type: number
          description: RTP used for house margin calculations (echoed from request)
          example: 0.97
        generatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this batch was generated
          example: '2026-03-24T12:00:00.000Z'
    BulkGameState:
      type: object
      description: >
        A single fully pre-generated game — all cards dealt, all stage odds
        calculated.

        Equivalent to C# `HedgeEmGameState` (DataContract), minus
        session/table/bet fields.


        The `handStageInfoList` contains one `BulkHandStageInfo` entry per hand
        per stage,

        ordered: all hands for HOLE, then FLOP, TURN, RIVER.

        Length = `numberOfHands × 4`.
      properties:
        gameId:
          type: string
          description: Unique game identifier within this batch (e.g. "BULK-0001")
          example: BULK-0001
        numberOfHands:
          type: integer
          example: 3
        numberOfBettingStages:
          type: integer
          description: Always 3 (HOLE, FLOP, TURN). RIVER is reveal-only — no betting.
          example: 3
        hands:
          type: array
          description: >-
            Hole card pairs, one per hand. Each string is two card codes e.g.
            "AcKd".
          items:
            type: string
          example:
            - AcKd
            - QsJs
            - 8h7c
        bc1:
          type: string
          description: Flop card 1
          example: Ah
        bc2:
          type: string
          description: Flop card 2
          example: 3s
        bc3:
          type: string
          description: Flop card 3
          example: 9d
        bc4:
          type: string
          description: Turn card
          example: 2c
        bc5:
          type: string
          description: River card
          example: Kh
        handStageInfoList:
          type: array
          description: >
            Flat list of per-hand per-stage data.

            Length = `numberOfHands × 4` (one entry per hand × per stage).

            Ordered by stage then hand: HOLE[0..n], FLOP[0..n], TURN[0..n],
            RIVER[0..n].
          items:
            $ref: '#/components/schemas/BulkHandStageInfo'
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid tableId.
    BulkHandStageInfo:
      type: object
      description: |
        Per-hand, per-stage odds and status data.
        Equivalent to C# `HedgeEmHandStageInfo` (DataContract).
      properties:
        handIndex:
          type: integer
          description: Zero-based hand index (0 to numberOfHands-1)
          minimum: 0
          example: 0
        bettingStage:
          $ref: '#/components/schemas/BettingStage'
        percentWin:
          type: number
          description: Probability of this hand winning outright (0–100)
          example: 62.4
        percentDraw:
          type: number
          description: Probability of a draw (0–100)
          example: 2.1
        percentWinOrDraw:
          type: number
          description: percentWin + percentDraw, rounded to 1 dp
          example: 64.5
        oddsActual:
          type: number
          description: True mathematical odds (1 / winProbability)
          example: 1.55
        oddsMargin:
          type: number
          description: Odds after house margin applied (oddsActual × targetRtp)
          example: 1.5
        oddsRounded:
          type: number
          description: Display odds, rounded to the nearest 0.1. Shown to player as "1:X".
          example: 1.5
        actualRtp:
          type: number
          description: Achieved RTP after rounding (oddsRounded / oddsActual)
          example: 0.968
        roundingRake:
          type: number
          description: >-
            Additional house take from rounding ((oddsMargin - oddsRounded) /
            oddsActual)
          example: 0
        statusIsWinner:
          type: boolean
          description: True at RIVER stage only if this hand wins (or ties)
          example: false
        statusCantLose:
          type: boolean
          description: >-
            True if this hand cannot be beaten at this stage (win% + draw% ≥
            99.9%)
          example: false
        statusIsFavourite:
          type: boolean
          description: True if this hand has the highest win percentage at this stage
          example: true
        statusBestRtp:
          type: boolean
          description: >-
            True if this hand offers the best value (highest display odds) at
            this stage
          example: false
        bestFiveCards:
          type: string
          nullable: true
          description: >-
            Space-separated best five cards. Null at HOLE stage (only 2 cards
            known).
          example: Ac Kd Ah 3s 9d
        handDescShort:
          type: string
          nullable: true
          description: Short hand description e.g. "Two Pair". Null at HOLE stage.
          example: Two Pair
        handDescLong:
          type: string
          nullable: true
          description: >-
            Long hand description e.g. "Two Pair, Aces and Kings". Null at HOLE
            stage.
          example: Two Pair, Aces and Kings
    BettingStage:
      type: integer
      description: |
        The current betting stage.
        - `-1` NON_BETTING — no bets accepted (river, setup)
        - `0` HOLE — betting on hole cards
        - `1` FLOP — betting on flop cards
        - `2` TURN — betting on turn card
      enum:
        - -1
        - 0
        - 1
        - 2
      example: 0
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error: betAmount must be a positive number.
    Unauthorized:
      description: Missing or invalid Bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error: Missing or invalid Authorization header.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase Auth JWT. Obtain via Supabase Auth sign-in.

````