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

# Get Balance

> Check the balance of all the accounts you have access to

## Path Parameters

<ParamField path="merchantId" type="string" required>
  Merchant ID
</ParamField>

## Query Parameters

<ParamField query="currency" type="string">
  Currency code of your deposit account. If not provided, the default value will be DRE.

  Allowed values: `USD`, `AUD`, `EUR`, `GBP`, `BRL`, `CAD`, `CHF`

  Example: `BRL`
</ParamField>

<ParamField query="recipient_id" type="string">
  ID of your recipient

  Example: `12`
</ParamField>

## Response

This status is returned in the following scenarios:

* The search was successful
* When the currency is incorrectly provided, the return will have this status with zeroed values
* When the merchant has no accounts, the return will have this status with zeroed values

<ResponseField name="balance" type="number">
  Example: `12000`
</ResponseField>

<ResponseField name="available_balance" type="number">
  Example: `10000`
</ResponseField>

<ResponseField name="reserve_balance" type="number">
  Example: `0`
</ResponseField>

<ResponseField name="fee" type="number or null">
  This field will only be different from null when the account is configured to receive fees in a wallet. Other than in this case, the balance of the other fee account(wallet) that will receive the fees is returned.

  Default: `null`

  Example: `100`
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/balance' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer {token}'
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "balance": 10000,
    "available_balance": 10000,
    "reserve_balance": 0
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>

## Response Fields

### balance

The total balance in the account.

### available\_balance

The balance available for withdrawal or transactions.

### reserve\_balance

The amount held in reserve (if applicable).

### fee

Fee balance (only applicable when the account is configured to receive fees in a wallet).

## Use Cases

<AccordionGroup>
  <Accordion title="Check Available Funds">
    Before processing a transaction, check if the merchant has sufficient available balance:

    ```javascript theme={null}
    const balance = await getBalance(merchantId);
    if (balance.available_balance >= transactionAmount) {
      // Proceed with transaction
    } else {
      // Insufficient funds
    }
    ```
  </Accordion>

  <Accordion title="Multi-Currency Balance">
    Check balances across different currencies:

    ```javascript theme={null}
    const currencies = ['USD', 'BRL', 'EUR'];
    const balances = await Promise.all(
      currencies.map(currency => 
        getBalance(merchantId, { currency })
      )
    );
    ```
  </Accordion>

  <Accordion title="Monitor Reserve Balance">
    Track the reserve balance to ensure compliance with reserve requirements:

    ```javascript theme={null}
    const balance = await getBalance(merchantId);
    if (balance.reserve_balance < requiredReserve) {
      // Alert: Reserve below threshold
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

### Invalid Currency

When an invalid currency is provided, the API returns a 200 status with zeroed values:

```json theme={null}
{
  "balance": 0,
  "available_balance": 0,
  "reserve_balance": 0
}
```

### No Accounts

When the merchant has no accounts, the API returns a 200 status with zeroed values:

```json theme={null}
{
  "balance": 0,
  "available_balance": 0,
  "reserve_balance": 0
}
```

## Best Practices

<Note>
  **Cache Balance Data**: Balance information doesn't change frequently. Consider caching the response for a short period (e.g., 1-5 minutes) to reduce API calls.
</Note>

<Warning>
  **Check Available Balance**: Always use `available_balance` rather than `balance` when determining if funds are available for transactions, as `balance` includes reserved amounts.
</Warning>