> For the complete documentation index, see [llms.txt](https://docs.thndr.io/integration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thndr.io/integration/operator-api/pending-matches.md).

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