> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4casters.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get bet by user reference

> Look up every bet tied to a client-defined identifier

Look up every bet tied to a `userReference`. `userReference` is an optional client-defined string you can attach to an order at place time to track it on your side — this endpoint is the read counterpart.

The response separates results into three buckets:

* `unmatched` — open offers from this reference that are still resting on the book.
* `matched`   — matched (ungraded) bets from this reference.
* `graded`    — graded (settled) bets from this reference, including `risk`, `win`, `fee`, and `result`.

## Request

`GET /user/getBetByUserReference`

<ParamField query="userReference" type="string" required>
  Client-defined reference passed in at place time.
</ParamField>

<ParamField query="gameID" type="string" required>
  Scope the lookup to a single game.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.4casters.io/user/getBetByUserReference?userReference=my-order-1&gameID=67d1c942215edc7ee0c806ef" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

## Response

<ResponseField name="data.unmatched" type="array">
  Open orders — same shape as [Get unmatched orders](/pages/rest/user/get-unmatched-orders#response).
</ResponseField>

<ResponseField name="data.matched" type="array">
  Matched (ungraded) bets — same shape as [Get matched bets](/pages/rest/user/get-matched-bets#response).
</ResponseField>

<ResponseField name="data.graded" type="array">
  Graded (settled) bets — same shape as [Get graded wagers](/pages/rest/user/get-graded-wagers#response).
</ResponseField>

## Errors

| Status | Meaning                              |
| ------ | ------------------------------------ |
| `408`  | `userReference` or `gameID` missing. |


## OpenAPI

````yaml GET /user/getBetByUserReference
openapi: 3.1.0
info:
  title: 4casters REST API
  version: 1.0.0
  description: >-
    Public REST API for the 4casters peer-to-peer betting exchange. Use this API
    to manage your account, query the orderbook and games, and place / edit /
    cancel orders.


    All responses (unless noted otherwise) are JSON envelopes of the form `{
    "data": ... }`.
  contact:
    name: 4casters
    url: https://4casters.io
servers:
  - url: https://api.4casters.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Login and account session management
  - name: User
    description: Read account info, bets, and orders
  - name: Orders
    description: Place, edit, look up, and cancel orders
  - name: Markets
    description: Browse leagues, games, participants, and orderbooks
  - name: Affiliate
    description: Affiliate / referral commission
paths:
  /user/getBetByUserReference:
    get:
      tags:
        - User
      summary: Get bet by user reference
      description: >-
        Look up every bet tied to a `userReference`. `userReference` is an
        optional client-defined string you can attach to an order at place time
        to track it on your side.


        Returns three arrays scoped to a single `gameID`:


        - `unmatched` — open offers from this reference that are still resting
        on the book.

        - `matched`   — matched (ungraded) bets from this reference.

        - `graded`    — graded (settled) bets from this reference, including
        risk, win, fees, and result.
      parameters:
        - name: userReference
          in: query
          required: true
          schema:
            type: string
          description: The client-defined reference passed in at place time.
        - $ref: '#/components/parameters/GameID'
      responses:
        '200':
          $ref: '#/components/responses/CombinedWagers'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '408':
          description: Invalid User Reference or Game ID
components:
  parameters:
    GameID:
      name: gameID
      in: query
      required: true
      schema:
        type: string
      description: >-
        A 4casters game id (`ObjectID`). Get game ids from `GET
        /exchange/v2/getGames` or `GET /exchange/v2/getOrderbook`.
  responses:
    CombinedWagers:
      description: >-
        Three-bucket wager view: open (`unmatched`), filled-but-not-graded
        (`matched`), and settled (`graded`).
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  unmatched:
                    type: array
                    items:
                      $ref: '#/components/schemas/UnmatchedOrder'
                  matched:
                    type: array
                    items:
                      $ref: '#/components/schemas/MatchedBet'
                  graded:
                    type: array
                    items:
                      $ref: '#/components/schemas/GradedWager'
    Unauthorized:
      description: Missing or invalid auth token
  schemas:
    UnmatchedOrder:
      type: object
      description: An open order that is currently resting on the exchange.
      properties:
        id:
          type: string
        txID:
          type: string
        type:
          $ref: '#/components/schemas/MarketType'
        bet:
          type: number
        odds:
          type: integer
        spread:
          type: number
          nullable: true
        total:
          type: number
          nullable: true
        participantID:
          type: string
          description: Present for `moneyline` / `spread`.
        otherParticipantID:
          type: string
          description: The opposite participant id (the one whose side is being offered).
        expiry:
          type: string
          format: date-time
          nullable: true
        filled:
          type: number
        offered:
          type: number
        remaining:
          type: number
        takenRatio:
          type: number
        createdAt:
          type: string
          format: date-time
        origin:
          type: string
          description: '`offer` or `wager`.'
        graded:
          type: boolean
        closed:
          type: boolean
        adminRefund:
          type: boolean
        userReference:
          type: string
        wagerRequestID:
          type: string
        game:
          $ref: '#/components/schemas/GameSummary'
    MatchedBet:
      type: object
      description: A bet that has been matched but not yet graded.
      properties:
        id:
          type: string
        txID:
          type: string
        type:
          $ref: '#/components/schemas/MarketType'
        bet:
          type: number
        odds:
          type: integer
        spread:
          type: number
          nullable: true
        total:
          type: number
          nullable: true
        OU:
          type: string
          enum:
            - over
            - under
          description: Present for `total`.
        participantID:
          type: string
          description: Present for `moneyline` / `spread`.
        market:
          type: string
          description: Present for `moneyline1x2`.
        side:
          $ref: '#/components/schemas/MarketSide'
        userReference:
          type: string
        createdAt:
          type: string
          format: date-time
        matchedTime:
          type: string
          format: date-time
        graded:
          type: boolean
        closed:
          type: boolean
        origin:
          type: string
          description: '`offer` or `wager`.'
        adminRefund:
          type: boolean
        risk:
          type: string
        win:
          type: string
        fee:
          type: string
        game:
          $ref: '#/components/schemas/GameSummary'
    GradedWager:
      type: object
      description: A settled wager.
      properties:
        id:
          type: string
        txID:
          type: string
        ticketNumber:
          type: string
        type:
          $ref: '#/components/schemas/MarketType'
        outcome:
          type: string
          enum:
            - winner
            - loser
            - push
            - refund
        bet:
          type: number
        odds:
          type: integer
        spread:
          type: number
          nullable: true
        total:
          type: number
          nullable: true
        OU:
          type: string
          enum:
            - over
            - under
        participantID:
          type: string
        market:
          type: string
        side:
          $ref: '#/components/schemas/MarketSide'
        matchedTime:
          type: string
          format: date-time
        settledAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        graded:
          type: boolean
        closed:
          type: boolean
        cancelled:
          type: boolean
        adminRefund:
          type: boolean
        platform:
          type: string
          example: api
        fee:
          type: string
          description: Commission charged on the matched portion.
        risk:
          type: string
        win:
          type: string
        result:
          type: string
          description: Net P&L on this wager (signed).
        pinnacleLine:
          type: object
          description: >-
            Snapshot of the comparable Pinnacle line at fill time, when
            available.
        game:
          $ref: '#/components/schemas/GameSummary'
    MarketType:
      type: string
      enum:
        - moneyline
        - spread
        - total
        - moneyline1x2
      description: >-
        Market type. `moneyline1x2` is **soccer-only** (three-way money line:
        home / away / draw).
    GameSummary:
      type: object
      properties:
        id:
          type: string
        league:
          type: string
        sport:
          type: string
        start:
          type: string
          format: date-time
        ended:
          type: boolean
        eventName:
          type: string
          nullable: true
        isFutures:
          type: boolean
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
    MarketSide:
      type: string
      description: |-
        Order side. Meaning depends on `type`:

        - `moneyline`, `spread` — the participant id you are backing.
        - `total` — `"over"` or `"under"`.
        - `moneyline1x2` — `"yes"` or `"no"` on the outcome named by `market`.
    Participant:
      type: object
      properties:
        id:
          type: string
        longName:
          type: string
        shortName:
          type: string
        homeAway:
          type: string
          enum:
            - home
            - away
        mainPitcher:
          type: string
          nullable: true
        rotationNumber:
          type: string
          nullable: true
        futuresSide:
          type: string
          nullable: true
        score:
          type: number
          description: Final score; only present for ended games.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Pass your auth token in the `Authorization` header. The `Bearer` prefix
        is optional; the server also accepts a signed `auth` cookie or a `token`
        field in the request body.

````