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

# Available Balance

> Retrieve your current merchant wallet balance, including available and locked funds.

# Available Balance

The Available Balance API allows you to retrieve the current wallet balance for your authenticated merchant account.

It returns the total balance, available balance, locked balance, and wallet currency. This endpoint is useful before initiating disbursements, payouts, or reconciliation.

> **Tip**
> Always check your available balance before initiating a disbursement or payout to avoid insufficient balance errors.

***

## Endpoint

```http theme={null}
GET /merchant-balance
```

***

## Authentication

Every request must include your API credentials.

| Header       | Required | Description         |
| ------------ | :------: | ------------------- |
| X-API-KEY    |     ✅    | Merchant API Key    |
| X-API-SECRET |     ✅    | Merchant API Secret |

***

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request GET \
      --url https://api.splashpay.co.tz/api/v1/merchant-balance \
      --header "X-API-KEY: pk_live_xxxxxxxxx" \
      --header "X-API-SECRET: sk_live_xxxxxxxxx"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.splashpay.co.tz/api/v1/merchant-balance",
      {
        method: "GET",
        headers: {
          "X-API-KEY": process.env.SPLASHPAY_KEY,
          "X-API-SECRET": process.env.SPLASHPAY_SECRET,
        },
      }
    );

    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        "https://api.splashpay.co.tz/api/v1/merchant-balance",
        headers={
            "X-API-KEY": "pk_live_xxxxxxxxx",
            "X-API-SECRET": "sk_live_xxxxxxxxx",
        },
    )

    print(response.json())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $client = new \GuzzleHttp\Client();

    $response = $client->get(
        'https://api.splashpay.co.tz/api/v1/merchant-balance',
        [
            'headers' => [
                'X-API-KEY' => 'pk_live_xxxxxxxxx',
                'X-API-SECRET' => 'sk_live_xxxxxxxxx',
            ],
        ]
    );

    echo $response->getBody();
    ```
  </Tab>
</Tabs>

***

## Example Response

```json theme={null}
{
    "status": "success",
    "code": "SUCCESS",
    "message": "Success",
    "data": {
        "balance": 28394,
        "available_balance": 28394,
        "locked_balance": 0,
        "currency": "TZS"
    },
    "meta": [],
    "request_id": "a17ec7ed-2ab3-406c-a811-4a6c730ebd09"
}
```

***

## Response Fields

| Field              | Type   | Description                                        |
| ------------------ | ------ | -------------------------------------------------- |
| balance            | number | Total wallet balance.                              |
| available\_balance | number | Funds currently available for transactions.        |
| locked\_balance    | number | Funds temporarily reserved or unavailable for use. |
| currency           | string | Wallet currency. Currently `TZS`.                  |

***

## Error Response

```json theme={null}
{
    "status": "error",
    "code": "UNAUTHORIZED",
    "message": "Unauthenticated."
}
```

```json theme={null}
{
    "status": "error",
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Access denied."
}
```

***

##