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

# Get Balance

> Retrieves the current balance of a player based on their player ID.

> `GET` /balance

### Headers

| Name                                                                | Type     | Description                                                                                                                   |
| ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>X-Auth-Token</span>** | `string` | Custom authentication header in the format X-Auth-Token: your\_token\_here. This token is required to authorize API requests. |

***

### Request Parameters

| Name                                                                       | Type     | Description                                                                                                                                     |
| -------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>playerId</span>**            | `string` | Unique identifier of the player whose balance is being retrieved.                                                                               |
| **<span style={{color: "rgb(var(--primary)"}}>gameUuid</span>**            | `string` | Unique identifier of the game for which the request is being made.                                                                              |
| **<span style={{color: "rgb(var(--primary)"}}>sessionId</span>**           | `string` | Unique identifier of the player's session.                                                                                                      |
| **<span style={{color: "rgb(var(--primary)"}}>promotionExternalId</span>** | `string` | External identifier of the promotion session. This parameter must be sent for promo or free bet requests and omitted for regular game requests. |
| **<span style={{color: "rgb(var(--primary)"}}>currency</span>**            | `string` | The currency code for the transaction, typically in ISO 4217 format.                                                                            |

***

### Response Parameters

| Name                                                           | Type      | Description                        |
| -------------------------------------------------------------- | --------- | ---------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>balance</span>** | `decimal` | The current balance of the player. |

***

### Error

<Note>If an error occurs while processing a request, the API must return a response with `HTTP Status Code: 400 Bad Request`</Note>

| Name                                                               | Type     | Description                               |
| ------------------------------------------------------------------ | -------- | ----------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>error\_code</span>** | `string` | Error code describing the specific issue. |

<Expandable title="Possible Error Codes">
  | Error Code                                                              | Description                                                         |
  | ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
  | **<span style={{color: "rgb(var(--primary)"}}>INVALID\_SESSION</span>** | The provided session ID is invalid or does not exist in the system. |
  | **<span style={{color: "rgb(var(--primary)"}}>TECHNICAL\_ERROR</span>** | An unexpected error occurred.                                       |
  | **<span style={{color: "rgb(var(--primary)"}}>NOT\_AUTHORIZED</span>**  | The request is not authorized due to invalid X-Auth-Token header.   |
</Expandable>

***

<Warning>
  Responsibility of the wallet platform
</Warning>

Assert that the incoming sessionId is valid, and return the player’s current balance.

If `promotionExternalId` is present, resolve the balance in the context of the promo or free bet session identified by this value.

<ResponseExample>
  ```http Request theme={null}
  GET /balance?playerId=123e4567-e89b-12d3-a456-426614174000
  &sessionId=abc123-session-id&promotionExternalId=promo-session-123&currency=USD&gameUuid=game-uuid-456
  ```

  ```json Response 200 theme={null}
  {
      "balance": 100.00
  }
  ```

  ```json Error 400 theme={null}
  {
      "error_code": "INVALID_SESSION"
  }
  ```
</ResponseExample>