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

# Get Merchant Balance

> Retrieve the current balance of a merchant's wallet

## Endpoint

```
GET /api/v1/merchants/{merchantID}/balance
```

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key. Must have **Read Balance** permission.
</ParamField>

## Path Parameters

<ParamField path="merchantID" type="string" required>
  The unique identifier of the merchant. Must match the merchant ID associated with the API key.
</ParamField>

## Response

<ResponseField name="balance" type="string">
  The current balance of the merchant's wallet as a decimal string (e.g., "50000.00")
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/balance" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.get(
    'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/balance',
    {
      headers: {
        'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'
      }
    }
  );

  console.log('Balance:', response.data.balance);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/balance',
      headers={'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'}
  )

  print('Balance:', response.json()['balance'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "balance": "50000.00"
  }
  ```

  ```json 403 Forbidden - Merchant ID Mismatch theme={null}
  {
    "type": "/problems/access-forbidden",
    "status": 403,
    "title": "Access Forbidden",
    "detail": "Merchant ID does not match API key"
  }
  ```

  ```json 403 Forbidden - Missing Permission theme={null}
  {
    "type": "/problems/access-forbidden",
    "status": 403,
    "title": "Access Forbidden",
    "detail": "API key does not have Read Balance permission"
  }
  ```
</ResponseExample>

## Use Cases

* **Balance Monitoring**: Automated alerts when balance reaches a threshold
* **Dashboard Integration**: Display current balance in POS or admin systems
* **Reconciliation**: Regular balance checks for accounting purposes
* **Pre-payout Validation**: Check available balance before requesting payouts

## Example: Balance Monitoring Script

```javascript theme={null}
const axios = require('axios');

const MERCHANT_ID = 'a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d';
const API_KEY = process.env.UNIVERSAL_WALLET_API_KEY;
const ALERT_THRESHOLD = 100000.00;

async function checkBalance() {
  try {
    const response = await axios.get(
      `https://api.yourdomain.com/api/v1/merchants/${MERCHANT_ID}/balance`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const balance = parseFloat(response.data.balance);
    console.log(`Current balance: ${balance}`);

    if (balance >= ALERT_THRESHOLD) {
      console.log('Balance above threshold - consider requesting a payout');
      // Send notification
    }

    return balance;
  } catch (error) {
    console.error('Failed to check balance:', error.message);
  }
}

// Run every hour
setInterval(checkBalance, 60 * 60 * 1000);
checkBalance(); // Initial check
```