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

# Sit at table

> Seats a player at a table with a specified buy-in amount.
The buy-in is deducted from the player's **account balance** (`wallets.balance`)
and credited to their **seat balance** (`game_table_state.seat_balance`).

Returns `NACK` with a message if the player's wallet balance is insufficient.

To reverse this operation (return chips to wallet), call
`POST /api/tables/{tableId}/leave`.

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




## OpenAPI

````yaml /openapi.yaml post /api/tables/{tableId}/sit
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}/sit:
    post:
      tags:
        - Tables
      summary: Sit at table
      description: >
        Seats a player at a table with a specified buy-in amount.

        The buy-in is deducted from the player's **account balance**
        (`wallets.balance`)

        and credited to their **seat balance**
        (`game_table_state.seat_balance`).


        Returns `NACK` with a message if the player's wallet balance is
        insufficient.


        To reverse this operation (return chips to wallet), call

        `POST /api/tables/{tableId}/leave`.


        Equivalent to `ws_sit_at_table_new` in the legacy C# server.
      operationId: sitAtTable
      parameters:
        - $ref: '#/components/parameters/tableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SitRequest'
            example:
              playerId: abc123
              buyInAmount: 500
      responses:
        '200':
          description: Seat assignment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SitResponse'
              example:
                acknowledgement: ACK
                seatId: 1
                seatBalance: 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:
    SitRequest:
      type: object
      required:
        - playerId
        - buyInAmount
      properties:
        playerId:
          type: string
          example: abc123
        buyInAmount:
          type: number
          minimum: 0.01
          example: 500
    SitResponse:
      type: object
      properties:
        acknowledgement:
          type: string
          enum:
            - ACK
            - NACK
        seatId:
          type: integer
          example: 1
        seatBalance:
          type: number
          example: 500
        message:
          type: string
          description: Present on NACK — reason for rejection (e.g. insufficient balance).
          example: 'Insufficient balance. Wallet: £250.00, requested: £500.00'
    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.

````