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

# Place a bet

> Places a bet on a specific hand at the current betting stage.

Bets are only accepted when the game is in an active betting stage
(Hole, Flop, or Turn). The odds recorded at the time of the bet are
stored alongside it for payout calculation.

Equivalent to `ws_place_bet` in the legacy C# server.




## OpenAPI

````yaml /openapi.yaml post /api/tables/{tableId}/bet
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/tables/{tableId}/bet:
    post:
      tags:
        - Tables
      summary: Place a bet
      description: |
        Places a bet on a specific hand at the current betting stage.

        Bets are only accepted when the game is in an active betting stage
        (Hole, Flop, or Turn). The odds recorded at the time of the bet are
        stored alongside it for payout calculation.

        Equivalent to `ws_place_bet` in the legacy C# server.
      operationId: placeBet
      parameters:
        - $ref: '#/components/parameters/tableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceBetRequest'
            example:
              playerId: abc123
              seatIndex: 0
              handIndex: 1
              betAmount: 25
      responses:
        '200':
          description: Bet acknowledgement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceBetResponse'
              examples:
                accepted:
                  summary: Bet accepted
                  value:
                    acknowledgement: ACK
                    message: Bet placed successfully.
                    updatedSeatBalance: 475
                rejected:
                  summary: Bet rejected (hand is dead)
                  value:
                    acknowledgement: NACK
                    message: Cannot place bet on a dead hand.
                    updatedSeatBalance: 500
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    tableId:
      name: tableId
      in: path
      required: true
      description: Unique numeric table identifier
      schema:
        type: integer
        minimum: 1
        example: 1
  schemas:
    PlaceBetRequest:
      type: object
      required:
        - playerId
        - seatIndex
        - handIndex
        - betAmount
      properties:
        playerId:
          type: string
          example: abc123
        seatIndex:
          type: integer
          minimum: 0
          example: 0
        handIndex:
          type: integer
          minimum: 0
          maximum: 3
          description: Which of the four hands to bet on
          example: 1
        betAmount:
          type: number
          minimum: 0.01
          example: 25
    PlaceBetResponse:
      type: object
      properties:
        acknowledgement:
          type: string
          enum:
            - ACK
            - NACK
        message:
          type: string
          example: Bet placed successfully.
        updatedSeatBalance:
          type: number
          example: 475
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid tableId.
  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.

````