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

# Get Balance

> Returns merchant balance in cents

## Overview

Returns the current balance and overdraft limit for your merchant account. All amounts are returned in cents.

## Endpoint

```http theme={null}
GET /api/agent_balance
```

## Authentication

<ParamField header="API-KEY" type="string" required>
  Your CashQ API Key for authentication
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.cashqbot.com/api/agent_balance' \
    -H 'API-KEY: your_api_key_here'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.cashqbot.com/api/agent_balance', {
    method: 'GET',
    headers: {
      'API-KEY': 'your_api_key_here'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.get(
      'https://api.cashqbot.com/api/agent_balance',
      headers={'API-KEY': 'your_api_key_here'}
  )

  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, 'https://api.cashqbot.com/api/agent_balance');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'API-KEY: your_api_key_here'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Response

<ResponseField name="balance" type="object">
  Balance information for the merchant account

  <Expandable title="Balance properties">
    <ResponseField name="balance" type="integer">
      Current account balance in cents. For example, `1000` represents \$10.00
    </ResponseField>

    <ResponseField name="overdraft" type="integer">
      Overdraft limit in cents. This is the additional amount you can spend beyond your balance
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Example

<ResponseExample>
  ```json Success theme={null}
  {
    "balance": {
      "balance": 0,
      "overdraft": 2000
    }
  }
  ```

  ```json Error theme={null}
  {
    "error": {
      "message": "Invalid or missing API key",
      "code": "authentication_error"
    },
    "success": "false"
  }
  ```
</ResponseExample>

## Understanding the Response

### Balance Calculation

Your available funds = `balance` + `overdraft`

**Example:**

* Balance: 1000 cents (\$10.00)
* Overdraft: 2000 cents (\$20.00)
* **Available funds: 3000 cents (\$30.00)**

### When to Check Balance

<CardGroup cols={2}>
  <Card title="Before Transfers" icon="money-bill-transfer">
    Check balance before initiating large transfers to ensure sufficient funds
  </Card>

  <Card title="Regular Monitoring" icon="chart-line">
    Monitor balance regularly to avoid insufficient funds errors
  </Card>

  <Card title="After Deposits" icon="plus">
    Verify balance after adding funds to your account
  </Card>

  <Card title="Error Recovery" icon="triangle-exclamation">
    Check balance when receiving insufficient funds errors
  </Card>
</CardGroup>

## Error Responses

| Error Code              | Description                | Solution                                                  |
| ----------------------- | -------------------------- | --------------------------------------------------------- |
| `authentication_error`  | Invalid or missing API key | Verify your API key is correct and included in the header |
| `internal_server_error` | Server error occurred      | Retry the request after a brief delay                     |

## Best Practices

<AccordionGroup>
  <Accordion title="Cache balance appropriately">
    Don't check balance before every single transaction. Cache the balance for a reasonable time (e.g., 5 minutes) to reduce API calls.
  </Accordion>

  <Accordion title="Handle overdraft correctly">
    Remember to include overdraft when calculating available funds. Don't just check the balance field.
  </Accordion>

  <Accordion title="Convert to dollars for display">
    Balance is returned in cents. Always divide by 100 when displaying to users.
  </Accordion>

  <Accordion title="Monitor balance regularly">
    Set up automated monitoring to alert you when balance falls below a threshold.
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Money Transfer" icon="money-bill-transfer" href="/api-reference/transfer">
    Initiate a money transfer after confirming sufficient balance
  </Card>

  <Card title="Check Transfer" icon="magnifying-glass" href="/api-reference/check-transfer">
    Validate transfer details before execution
  </Card>
</CardGroup>