# Pending matches

Retrieves all pending matches for a given player.

### Endpoints

**Sandbox**

```
GET https://operator-sandbox.thndr-api.com/v1/pending-matches/{userId}
```

**Production**

```
GET https://operator.thndr-api.com/v1/pending-matches/{userId}
```

#### Path parameters

| Parameter | Type   | Description                                   |
| --------- | ------ | --------------------------------------------- |
| `userId`  | string | Player identifier on the Operator’s platform. |

#### Query parameters

| Parameter | Type    | Default | Description                                   |
| --------- | ------- | ------- | --------------------------------------------- |
| `limit`   | integer | `100`   | Maximum number of matches to return (min: 1). |
| `skip`    | integer | `0`     | Number of matches to skip for pagination.     |

#### Request headers

```
x-operator-id: your_operator_id
x-api-key: your_api_key
```

#### Response

Returns a paginated list of pending matches. Each match entry includes:

* A unique room identifier (`roomId`)
* The game type (`gameId`): one of `solitaire`, `blocks`, `blackjack`, `twentyone`, `slots`, `plinko`, `marbles`
* A unique round identifier (`roundId`)
* The player's round state (`roundState`) - see Round states below
* The round deadline (`roundDeadline`) - a Unix timestamp in milliseconds, only present when `roundState` is `STARTED`
* The opponent's state (`opponent`) - present when the match has been paired with an opponent; contains the same `roundState` and optional `roundDeadline` fields
* The match amounts (`amounts`) - contains `matchCurrency` (always USD) and `userCurrency` (the player's local currency), each with `currency`, `entryFee`, and `reward` fields
* Pagination metadata: `total`, `limit`, `skip`

```json
{
  "matches": [
    {
      "roomId": "room-123",
      "gameId": "solitaire",
      "roundId": "550e8400-e29b-41d4-a716-446655440000",
      "roundState": "STARTED",
      "roundDeadline": 1713256800000,
      "opponent": {
        "roundState": "NOT_STARTED"
      },
      "amounts": {
        "matchCurrency": {
          "currency": "USD",
          "entryFee": 1000,
          "reward": 2000
        },
        "userCurrency": {
          "currency": "EUR",
          "entryFee": 920,
          "reward": 1840
        }
      }
    }
  ],
  "total": 1,
  "limit": 100,
  "skip": 0
}
```

### Round states

Both the player and their opponent can each be in one of three states:

| State         | Description                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `NOT_STARTED` | The match timer has not started.                                                                             |
| `STARTED`     | The match timer has started and the player is actively playing. A `roundDeadline` timestamp will be present. |
| `FINISHED`    | The player has completed their round.                                                                        |

All combinations of player and opponent states are valid **except** both being `FINISHED` at the same time - once both players finish, the match is resolved and removed from the pending list.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thndr.io/integration/operator-api/pending-matches.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.