---
title: "Balances"
description: "Retrieve balance classifications and live amounts held for payouts and refunds."
canonical: "https://studio.inttegro.com/api/balances"
format: inttegro-machine-docs/v1
language: "Python"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/python/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 555
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "general"
recommended_mcp_tools: ["get_balances"]
estimated_tokens: 2728
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Retrieve balance classifications and live amounts held for payouts and refunds. This Python representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. When should the reader use Balances?

Use this API reference when exact operations, fields, states, or errors are required.

#### Q2. What is authoritative on this page?

Types and enum members link to pinned SDK references; a response field may link only to its containing type. A “wire-only” request field is not a verified native SDK member.

#### Q3. What page-specific constraint matters most?

Prioritize the machine-only guidance “Interpret balances and holds correctly”: Keep calculations separated by currency and use each currency's smallest unit. Do not treat an integer amount as a major-unit decimal. The snapshot classifications are,,, and. Do not add to the snapshot buckets. Holds describe commitments…

#### Q4. Can Inttegro MCP materially help with this task?

Yes, when the reader has an authenticated MCP connection and the task needs live context, guided planning, or a supported operation. The strongest matches are `get_balances`; their exact roles and boundaries are listed below.

#### Q5. How should the reader verify the answer and continue?

For a read, compare the returned resource with the requested identifier and scope. For a write, preserve its identifier and retrieve authoritative current state before declaring the business outcome complete. Continue with [Understand payout settings](https://studio.inttegro.com/machine/python/guides/understand-payout-settings.md) and [Schedule a payout](https://studio.inttegro.com/machine/python/api/payouts.md#schedule-a-payout) when those concerns enter scope.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_balances`](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#get_balances) — read; no mutation confirmation. Gets current balance snapshots by currency with exact familiar-unit amounts and supplemental machine-readable minor units. This tool cannot move funds.

## Document content

# Balances

The Balances API reports how funds are classified and how much is currently committed to payout or refund operations. Use it to power finance dashboards, plan payouts, and reconcile the funds collected through Inttegro.

The four root amount fields come from the latest completed transaction
snapshot. [`balances.ghs.held`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) is a live overlay showing
funds committed to in-flight or unresolved payouts and refunds. It is not a
fifth balance bucket.

## Interpret balances and holds correctly

- Keep calculations separated by currency and use each currency's smallest
  unit. Do not treat an integer amount as a major-unit decimal.
- The snapshot classifications are [`balances.ghs.available`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance), [`balances.ghs.pending`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance), [`balances.ghs.refund`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance), and [`balances.ghs.reserved`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance).
- Do not add [`balances.ghs.held`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) to the snapshot buckets. Holds describe commitments against the balance, not additional funds.
- Do not subtract holds from [`balances.ghs.available`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) to manufacture a live available amount. A completed snapshot may already reflect some holds. Use the payout or refund operation for its authoritative capacity check.
- [`balances.ghs.includes_transactions_before`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance)
  is the transaction cutoff for the snapshot.
  [`balances.ghs.held.as_of`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance)
  is when the live hold amounts were read. Do not treat either value as the
  meaning of the other.
- Use [Balance transactions](https://studio.inttegro.com/machine/python/api/balance-transactions.md#page-through-balance-transactions)
  and the relevant payout or refund record to explain a balance or hold.

## The balance object

Balances are grouped by currency. Every amount is an integer in that currency's smallest unit, such as pesewas for GHS.

[`balances.ghs.available`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance),
[`balances.ghs.pending`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance),
[`balances.ghs.refund`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance), and
[`balances.ghs.reserved`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) classify funds at the transaction
snapshot cutoff. [`balances.ghs.held`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) separately reports live
operational commitments.

### Properties

- [`ghs`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance)

  Latest GHS snapshot. Amounts are expressed in pesewas.

  - [`ghs.available`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

    Funds classified as available by the latest completed transaction snapshot.

    - [`ghs.available.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `integer`

      Available amount in minor units (pesewas for GHS).

  - [`ghs.held`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

    Live operational commitments against the balance. Do not add this object to the four snapshot buckets.

    - [`ghs.held.as_of`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `timestamp`

      Time at which Inttegro successfully read the hold amounts. This is not the last time a hold changed.

    - [`ghs.held.payout`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

      Funds committed to in-flight or unresolved payouts.

      - [`ghs.held.payout.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `integer`

        Amount currently held for payouts, in pesewas.

    - [`ghs.held.refund`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

      Funds committed to in-flight or unresolved refunds.

      - [`ghs.held.refund.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `integer`

        Amount currently held for refunds, in pesewas.

  - [`ghs.includes_transactions_before`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `timestamp`

    Transaction cutoff for the snapshot classifications. Transactions created before this time are included; transactions at or after it are not.

  - [`ghs.pending`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

    Funds recognized by the snapshot but not yet available, usually because they are still aging.

    - [`ghs.pending.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `integer`

      Pending amount in pesewas.

  - [`ghs.refund`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

    Funds intentionally earmarked for future refund obligations at the snapshot cutoff.

    - [`ghs.refund.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `integer`

      Refund-earmarked amount in pesewas.

  - [`ghs.reserved`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `object`

    Funds intentionally reserved for policy, risk, or remediation purposes at the snapshot cutoff.

    - [`ghs.reserved.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) — `integer`

      Policy-reserved amount in pesewas.

## Retrieve your balance

Retrieve the latest GHS balance classifications and current operational
holds. Read [`balances.ghs.held.payout.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) to see how
much is committed to payouts and
[`balances.ghs.held.refund.amount`](https://python.inttegro.dev/v12.0.0/inttegro/balance.html#Balance) to see how much is
committed to refunds.

A new account with no completed balance activity returns zero amounts. The response still includes both freshness timestamps.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request body

Send an empty JSON object. No balance ID or other request attributes are needed.

**Request — POST /balances**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.balances.get()
```

```json
{
  "balances": {
    "ghs": {
      "available": {
        "amount": 145000
      },
      "held": {
        "as_of": "2026-10-04T14:30:00.000Z",
        "payout": {
          "amount": 20000
        },
        "refund": {
          "amount": 3000
        }
      },
      "includes_transactions_before": "2024-12-24T14:00:00.000Z",
      "pending": {
        "amount": 32000
      },
      "refund": {
        "amount": 0
      },
      "reserved": {
        "amount": 0
      }
    }
  }
}
```

## Related resources

- [Understand balances](https://studio.inttegro.com/machine/python/guides/understand-balances.md) - Interpret snapshot classifications, live holds, and freshness.
- [Page through balance transactions](https://studio.inttegro.com/machine/python/api/balance-transactions.md#page-through-balance-transactions) - Inspect the entries behind a balance.
- [Schedule a payout](https://studio.inttegro.com/machine/python/api/payouts.md#schedule-a-payout) - Move eligible funds to a financial account.
- [Understand payout settings](https://studio.inttegro.com/machine/python/guides/understand-payout-settings.md) - Configure when
  automatic payouts run.