> For the complete documentation index, see [llms.txt](https://docs.xpayconnect.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xpayconnect.io/documentation/eng/finance/balance.md).

# Balance

> Method: **GET**
>
> Path: **/merchant/balance/{merchant\_id}**

## Request Parameters

| Parameter        | Type   | Required | Description                                                                                                               |
| ---------------- | ------ | :------: | ------------------------------------------------------------------------------------------------------------------------- |
| **merchant\_id** | string |     ✓    | Path parameter. Unique merchant name. Must belong to the API key owner, otherwise `Invalid merchant_id` (403) is returned |

### Request Examples

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const crypto = require('crypto');
const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const xApiKey = crypto.createHash('sha256').update(`${apiKey}|`).digest('hex');

const { data } = await axios.get('https://api.xpayconnect.io/merchant/balance/exMerchant', {
    headers: { 'client-api-key': apiKey, 'x-api-key': xApiKey },
});
```

{% endtab %}

{% tab title="Python" %}

```python
import hashlib
import requests

api_key = 'YOUR_API_KEY'
x_api_key = hashlib.sha256(f'{api_key}|'.encode()).hexdigest()

resp = requests.get('https://api.xpayconnect.io/merchant/balance/exMerchant', headers={
    'client-api-key': api_key,
    'x-api-key': x_api_key,
})
data = resp.json()
```

{% endtab %}

{% tab title="PHP" %}

```php
$apiKey = 'YOUR_API_KEY';
$xApiKey = hash('sha256', $apiKey . '|');

$ch = curl_init('https://api.xpayconnect.io/merchant/balance/exMerchant');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['client-api-key: ' . $apiKey, 'x-api-key: ' . $xApiKey],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
```

{% endtab %}
{% endtabs %}

***

## Response

```json
{
    "ok": true,
    "balance": "99999.99",
    "lockedBalance": "0.00",
    "payoutEnabled": true,
    "usdtBalance": "10000.000000",
    "currency": "RUB",
    "allowUsdt": false
}
```

| Field             | Type    | Description                                                                                                                          |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **ok**            | boolean | `true` on a successful request                                                                                                       |
| **balance**       | string  | Current merchant balance in the primary currency (2 decimal places)                                                                  |
| **lockedBalance** | string  | Locked funds — reserved for payouts being created or in progress (2 decimal places)                                                  |
| **payoutEnabled** | boolean | Whether payouts (`PAYOUT`) are enabled for the merchant. If `false`, `createOrder` calls with `direction: "PAYOUT"` will be rejected |
| **usdtBalance**   | string  | USDT balance (6 decimal places). Relevant when `allowUsdt: true`                                                                     |
| **currency**      | string  | Balance currency (`RUB`, `KGS`, `KZT`, or `UZS`)                                                                                     |
| **allowUsdt**     | boolean | Whether USDT conversion is enabled for the merchant                                                                                  |