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

# Top up chips

> Transfers chips from the player's **account balance** (`wallets.balance`) to
their **seat balance** (`game_table_state.seat_balance`).

Players can top up between games or between betting stages if their seat
balance is running low. Returns `NACK` with a message if the wallet balance
is insufficient. The response always includes `newAccountBalance` so the
client can update the lobby header immediately.

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




## OpenAPI

````yaml /openapi.yaml post /api/tables/{tableId}/topup
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}/topup:
    post:
      tags:
        - Tables
      summary: Top up chips
      description: >
        Transfers chips from the player's **account balance**
        (`wallets.balance`) to

        their **seat balance** (`game_table_state.seat_balance`).


        Players can top up between games or between betting stages if their seat

        balance is running low. Returns `NACK` with a message if the wallet
        balance

        is insufficient. The response always includes `newAccountBalance` so the

        client can update the lobby header immediately.


        Equivalent to `ws_top_up_chips_at_table` in the legacy C# server.
      operationId: topUpChips
      parameters:
        - $ref: '#/components/parameters/tableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpRequest'
            example:
              playerId: abc123
              amount: 100
      responses:
        '200':
          description: Top up acknowledgement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpResponse'
              example:
                acknowledgement: ACK
                newSeatBalance: 600
                newAccountBalance: 900
        '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:
    TopUpRequest:
      type: object
      required:
        - playerId
        - amount
      properties:
        playerId:
          type: string
          example: abc123
        amount:
          type: number
          minimum: 0.01
          example: 100
    TopUpResponse:
      type: object
      properties:
        acknowledgement:
          type: string
          enum:
            - ACK
            - NACK
        newSeatBalance:
          type: number
          example: 600
        newAccountBalance:
          type: number
          description: Wallet balance after deduction. Present on both ACK and NACK.
          example: 900
        message:
          type: string
          description: Present on NACK — reason for rejection.
          example: 'Insufficient balance. Wallet: £50.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.

````