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

# Get player

> Returns a player's profile, account balance, and personal table assignment.

On first call for a new OAuth user, automatically creates a `players` row
and a `wallets` row with a **£1,000 welcome balance**. Subsequent calls return
the live `wallets.balance` — reflecting any deposits, withdrawals, buy-ins,
and leave payouts since registration.

`accountBalance` is the lobby wallet (not the seat balance). To get the
seat balance at a specific table, call `GET /api/tables/{tableId}/state`.

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




## OpenAPI

````yaml /openapi.yaml get /api/players/{playerId}
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/players/{playerId}:
    get:
      tags:
        - Players
      summary: Get player
      description: >
        Returns a player's profile, account balance, and personal table
        assignment.


        On first call for a new OAuth user, automatically creates a `players`
        row

        and a `wallets` row with a **£1,000 welcome balance**. Subsequent calls
        return

        the live `wallets.balance` — reflecting any deposits, withdrawals,
        buy-ins,

        and leave payouts since registration.


        `accountBalance` is the lobby wallet (not the seat balance). To get the

        seat balance at a specific table, call `GET
        /api/tables/{tableId}/state`.


        Equivalent to `ws_get_player_account_balance` in the legacy C# server.
      operationId: getPlayer
      parameters:
        - $ref: '#/components/parameters/playerId'
      responses:
        '200':
          description: Player profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HedgeEmPlayer'
              example:
                playerId: abc123
                username: simon.hewins@gmail.com
                displayName: Simon
                accountBalance: 1000
                avatarImageUrl: /avatars/user_square.jpg
                role: BASIC_USER
                isActive: true
                personalTableId: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    playerId:
      name: playerId
      in: path
      required: true
      description: Player UUID (from Supabase auth.users.id)
      schema:
        type: string
        format: uuid
        example: abc123-def456
  schemas:
    HedgeEmPlayer:
      type: object
      properties:
        playerId:
          type: string
          description: Supabase auth UUID
          example: abc123
        username:
          type: string
          example: simon.hewins@gmail.com
        displayName:
          type: string
          example: Simon
        accountBalance:
          type: number
          description: Total chips in the player's account (not at any table)
          example: 1000
        avatarImageUrl:
          type: string
          example: /avatars/user_square.jpg
        role:
          type: string
          enum:
            - UNSPECIFIED_DUE_TO_ERROR
            - BASIC_USER
            - PAYING_USER
            - ANON_USER
            - ADMIN
          example: BASIC_USER
        isActive:
          type: boolean
          example: true
        personalTableId:
          type: integer
          nullable: true
          description: The player's personal table ID, if they have one
          example: 1
    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.

````