> ## 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 Distributor Balance

> Retrieve the current balance of an distributor's wallet

## Endpoint

```
GET /api/v1/distributors/{distributorID}/balance
```

## Authentication

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

## Path Parameters

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

## Response

<ResponseField name="balance" type="string">
  The current balance of the distributor'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/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/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/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/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/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/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 - Distributor ID Mismatch theme={null}
  {
    "type": "/problems/access-forbidden",
    "status": 403,
    "title": "Access Forbidden",
    "detail": "Distributor 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 falls below threshold
* **Pre-transaction Validation**: Check if sufficient balance exists before attempting operations
* **Dashboard Integration**: Display current balance in POS or admin systems
* **Reconciliation**: Regular balance checks for accounting purposes

## Example: Balance Monitoring Script

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

const AGENT_ID = '36e48800-22ce-4ea0-b37a-198f7978cd53';
const API_KEY = process.env.UNIVERSAL_WALLET_API_KEY;
const MIN_BALANCE = 10000.00;

async function checkBalance() {
  try {
    const response = await axios.get(
      `https://api.yourdomain.com/api/v1/distributors/${AGENT_ID}/balance`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );
    
    const balance = parseFloat(response.data.balance);
    console.log(`Current balance: ${balance}`);
    
    if (balance < MIN_BALANCE) {
      console.warn('⚠️ Balance below minimum threshold!');
      // Send alert email/SMS
    }
    
    return balance;
  } catch (error) {
    console.error('Failed to check balance:', error.message);
  }
}

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