# Accounts & Balances

> How to query Alpha Ladder account summaries and per-currency detail using get_account_summary, get_account_detail, and get_module_permissions.

Alpha Ladder accounts are partitioned into product sub-accounts. Three read-only tools let you inspect the current state of any account without side effects. For the full account model definition, see [Concepts](/developers/financial-services/concepts).

---

## get_account_summary

Retrieve a high-level balance overview across all product accounts, expressed in USD.

**Parameters**

None.

**Returns**

An object with one key per product account category. Each category contains the same three fields:

| Field | Type | Description |
|---|---|---|
| `availableAmount` | string | Amount available for immediate use, in USD (high-precision decimal string) |
| `pendingAmount` | string | Aggregate pending debit — funds reserved for outgoing transactions, in USD |
| `totalAmount` | string | Total balance including pending, in USD |

**Categories returned:**

| Key | Description |
|---|---|
| `fiat` | Fiat currency balance |
| `investment_fiat` | Fiat locked in investment products |
| `quarantine_portfolio` | Assets under compliance quarantine |
| `investment_product` | Balance held in investment products |

All amounts are in USD (the display currency) as high-precision decimal strings. Read-only.

---

## get_account_detail

Fetch a per-currency breakdown for a specific product account.

**Parameters**

| Name | Type | Required | Notes |
|---|---|---|---|
| `productCode` | string (enum) | yes | One of: `fiat`, `investment_fiat`, `quarantine_portfolio`, `investment_product`, `named_account` |

**`productCode` values:**

| Value | Meaning |
|---|---|
| `fiat` | Fiat currency account (USD, HKD, EUR, etc.) |
| `investment_fiat` | Fiat funds locked in investment products |
| `quarantine_portfolio` | Assets frozen under compliance review |
| `investment_product` | Balance in investment products (FIP); `instrumentInfoMap` is always `{}` |
| `named_account` | Same-name account — funds in accounts registered under the holder's own name |

**Returns (success)**

```json
{
  "data": {
    "holderCode": "IOTH0001",
    "productCode": "fiat",
    "availableAmount": "12345.67",
    "pendingAmount": "500.00",
    "totalAmount": "12845.67",
    "instrumentInfoMap": {
      "USD": {
        "availableAmount": "12000.00",
        "availableAmountDisplay": "12000.00",
        "pendingAmount": "500.00",
        "pendingCreditAmount": "0.00"
      },
      "HKD": { ... }
    }
  }
}
```

| Field | Type | Description |
|---|---|---|
| `data.holderCode` | string | Account holder participant code |
| `data.productCode` | string | The product type queried |
| `data.availableAmount` | string | Aggregate available balance in USD |
| `data.pendingAmount` | string | Aggregate pending debit in USD |
| `data.totalAmount` | string | Aggregate total in USD |
| `data.instrumentInfoMap` | object | Per-currency breakdown, keyed by currency code. Empty (`{}`) for `investment_product`. |

**`instrumentInfoMap[currency]` fields:**

| Field | Type | Description |
|---|---|---|
| `availableAmount` | string | Available balance in the currency's native units (raw decimal string) |
| `availableAmountDisplay` | string | Available balance converted to USD (short decimal string) |
| `pendingAmount` | string | Outgoing pending debit in native units |
| `pendingCreditAmount` | string | Incoming pending credit in native units (not yet settled) |

Use `availableAmount` for same-currency comparisons (e.g. checking if the user has enough USD to withdraw 100 USD). Use `availableAmountDisplay` for cross-currency value comparisons in user-facing displays.

**Returns (error / re-auth)**

When the session has expired or the request fails, the tool returns an error object instead:

```json
{
  "error": true,
  "message": "Session expired",
  "authUrl": "https://www.alphaladder.hk/auth/..."
}
```

See [Concepts — Error and re-authentication shape](/developers/financial-services/concepts#error-and-re-authentication-shape) for full details. Read-only.

---

## get_module_permissions

Check which financial modules the current user has permission to access.

**Parameters**

None.

**Returns**

```json
{
  "permissions": [
    { "module": "deposit", "hasPermission": true },
    { "module": "otc", "hasPermission": true },
    { "module": "withdrawal", "hasPermission": false },
    { "module": "wealth", "hasPermission": true }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `permissions` | array | One entry per module |
| `permissions[].module` | string | Module identifier: `deposit`, `otc`, `withdrawal`, or `wealth` |
| `permissions[].hasPermission` | boolean | Whether the user can access this module |

Call this tool before attempting any module-specific operation. If `hasPermission` is `false`, do not attempt the operation and inform the user that access is not enabled for their account. Read-only.