> ## 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.

# Deal hands

> Shuffles a fresh deck, deals hole cards to N simultaneous hands, and returns
pre-flop win/draw odds for each hand.

This is the first call in a new game — it replaces the combined effect of:
- `HedgeEmUtility.f_shuffle_deck` (5-pass Fisher-Yates shuffle)
- The `STATUS_START → STATUS_HOLE` transition in `f_change_table_game_state`
- UMA math engine pre-flop equity calculation

**Odds engine (tactical):** Monte Carlo simulation via `poker-odds-calculator`
(100,000 iterations). The strategic replacement is the UMA C++ math engine
deployed as an HTTP microservice (HEDGE-43).

The hand with the highest `winPercentage` is marked `IN_PLAY_FAVOURITE`;
all others are `IN_PLAY_BETTING_STAGE_ACTIVE`.

The `remainingDeck` array contains the 44 undealt cards — these are the
pool from which the flop, turn, and river will be drawn.




## OpenAPI

````yaml /openapi.yaml post /api/deal
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/deal:
    post:
      tags:
        - Game
      summary: Deal hands
      description: >
        Shuffles a fresh deck, deals hole cards to N simultaneous hands, and
        returns

        pre-flop win/draw odds for each hand.


        This is the first call in a new game — it replaces the combined effect
        of:

        - `HedgeEmUtility.f_shuffle_deck` (5-pass Fisher-Yates shuffle)

        - The `STATUS_START → STATUS_HOLE` transition in
        `f_change_table_game_state`

        - UMA math engine pre-flop equity calculation


        **Odds engine (tactical):** Monte Carlo simulation via
        `poker-odds-calculator`

        (100,000 iterations). The strategic replacement is the UMA C++ math
        engine

        deployed as an HTTP microservice (HEDGE-43).


        The hand with the highest `winPercentage` is marked `IN_PLAY_FAVOURITE`;

        all others are `IN_PLAY_BETTING_STAGE_ACTIVE`.


        The `remainingDeck` array contains the 44 undealt cards — these are the

        pool from which the flop, turn, and river will be drawn.
      operationId: dealHands
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealRequest'
            example:
              numberOfHands: 4
      responses:
        '200':
          description: Shuffled hands and pre-flop odds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealResponse'
              example:
                hands:
                  - AcKd
                  - QsJs
                  - 8h7c
                  - 5d2c
                handOdds:
                  - handIndex: 0
                    bettingStage: 0
                    handStatus: IN_PLAY_FAVOURITE
                    winPercentage: 62.4
                    drawPercentage: 2.1
                    odds: 1.6
                  - handIndex: 1
                    bettingStage: 0
                    handStatus: IN_PLAY_BETTING_STAGE_ACTIVE
                    winPercentage: 21.3
                    drawPercentage: 1.8
                    odds: 4.69
                  - handIndex: 2
                    bettingStage: 0
                    handStatus: IN_PLAY_BETTING_STAGE_ACTIVE
                    winPercentage: 10.2
                    drawPercentage: 0.9
                    odds: 9.8
                  - handIndex: 3
                    bettingStage: 0
                    handStatus: IN_PLAY_BETTING_STAGE_ACTIVE
                    winPercentage: 6.1
                    drawPercentage: 0.5
                    odds: 16.39
                remainingDeck:
                  - 2c
                  - 3d
                  - 4h
                  - ...
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DealRequest:
      type: object
      properties:
        numberOfHands:
          type: integer
          description: Number of simultaneous hole card hands to deal (2–6, default 4)
          minimum: 2
          maximum: 6
          default: 4
          example: 4
    DealResponse:
      type: object
      properties:
        hands:
          type: array
          description: |
            Dealt hole card pairs. Each string is two concatenated card codes,
            e.g. `"AcKd"` = Ace of clubs + King of diamonds.
            See [Card Notation](/concepts/card-notation).
          items:
            type: string
          example:
            - AcKd
            - QsJs
            - 8h7c
            - 5d2c
        handOdds:
          type: array
          description: >
            Pre-flop odds for each hand. Same shape as the `handOdds` array in

            `HedgeEmGameState` — the game client renders these directly as
            betting panels.
          items:
            $ref: '#/components/schemas/HedgeEmHandOdds'
        remainingDeck:
          type: array
          description: >
            The 44 cards not yet in play. The flop (3 cards), turn (1), and
            river (1)

            will be drawn from this pool when the game advances.
          items:
            type: string
          example:
            - 2c
            - 3d
            - 4h
            - 5s
    HedgeEmHandOdds:
      type: object
      description: >
        Odds panel data for a single hand at a single betting stage.

        Used by the game client to render the 12 betting panels (4 hands × 3
        stages).
      properties:
        handIndex:
          type: integer
          minimum: 0
          maximum: 3
          example: 0
        bettingStage:
          $ref: '#/components/schemas/BettingStage'
        handStatus:
          $ref: '#/components/schemas/HandStatus'
        winPercentage:
          type: number
          description: Probability of this hand winning (0–100)
          example: 62.4
        drawPercentage:
          type: number
          description: Probability of a draw (0–100)
          example: 2.1
        odds:
          type: number
          description: |
            Payout odds. A bet of X returns X × odds.
            0.0 when the hand is Dead or in a non-betting stage.
          example: 1.6
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid tableId.
    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
    HandStatus:
      type: string
      description: >
        The display status of a hand's betting panel at a given stage.

        Used by the game client to render panels appropriately.

        - `IN_PLAY_DEAD` — hand cannot win; no bets accepted

        - `IN_PLAY_WILL_WIN` — hand is guaranteed to win or draw; no bets
        accepted

        - `IN_PLAY_FAVOURITE` — leading hand; bets accepted at lower odds

        - `IN_PLAY_WINNER` — revealed winner at river
      enum:
        - UNDEFINED
        - IN_NON_BETTING_STAGE
        - IN_PLAY_PREVIOUS_BETTING_STAGE_NOT_ACTIVE
        - IN_PLAY_BETTING_STAGE_ACTIVE
        - IN_PLAY_DISABLED
        - IN_PLAY_DEAD
        - IN_PLAY_FAVOURITE
        - IN_PLAY_WILL_WIN
        - IN_PLAY_WINNER
      example: IN_PLAY_FAVOURITE
  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.

````