Aggregated wallet balance across all entities

# Aggregated wallet balance across multiple entities

## Prerequisite: org-level token

This workflow requires an **org-level token** (not company-scoped). With a company-scoped token, `list_companies` returns only the current entity with `name: null`.

## 2-step workflow

### Step 1 — List all entities

```json
{
  "tool": "list_companies",
  "params": {}
}
```

Returns the list of accessible entities: `{ id, name }` per entity.

Example (11 entities on this account):
```json
[
  { "id": "B1stUp83",      "name": "SPENDESK" },
  { "id": "Hx1N5m87M",    "name": "Spendesk Limited" },
  { "id": "RRbRgeIB7X",   "name": "Spendesk GmbH" },
  { "id": "pD0gYhOK75T",  "name": "Spendesk Inc." },
  ...
]
```

### Step 2 — Get the wallet for each entity

For each returned `companyId`:
```json
{
  "tool": "get_wallet_summary",
  "params": {
    "companyId": "<entity id>"
  }
}
```

## Pitfall: list_companies doesn't guarantee access to all entities

`list_companies` lists all entities **known** to the token, but `get_wallet_summary` can return `"Failed to verify user company membership"` for some of them if the token doesn't have full access rights.

→ Always handle errors for each individual call. Continue with the accessible entities, flag the inaccessible ones.

Example observed on this account: `pD0gYhOK75T` (Spendesk Inc.) → error, despite appearing in `list_companies`.

## Observed data

### SPENDESK (EUR, B1stUp83)
- `totalAmount`: **-511,590 EUR** (negative balance — allocations > balance)
- `currency`: EUR

### Spendesk Limited (GBP, Hx1N5m87M)
- `totalAmount`: 75,662 GBP
- `totalAvailableAmount`: 49,941 GBP
- `totalAllocatedAmount`: 25,720 GBP
  - subscription: 4,983 GBP
  - physical: 7,238 GBP
  - singlePurchase: 1,395 GBP

## Different currencies — DO NOT sum without conversion

Each entity has its own functional currency. To aggregate into a single currency (e.g. EUR), exchange rates must be applied — **not provided by the Spendesk MCP**. Conversion must be handled client-side.

→ For a consolidated view in EUR: present each entity in its own currency, or inject exchange rates from an external source.

## Structure of get_wallet_summary

```json
{
  "id": "companyId",
  "name": "Entity name",
  "status": "active",
  "currency": "EUR",
  "totalAmount": { "amount": -51159000, "currency": "EUR", "precision": 2 },
  "totalAvailableAmount": { "amount": ..., "currency": "EUR", "precision": 2 },
  "totalAllocatedAmount": { "amount": ..., "currency": "EUR", "precision": 2 },
  "allocatedOnCards": {
    "subscriptionAmount": { ... },
    "physicalAmount": { ... },
    "singlePurchaseAmount": { ... },
    "totalAllocatedAmount": { ... }
  },
  "scheduledTransfersAmount": {
    "scheduledExpenseClaimsAmount": { ... },
    "scheduledInvoicesAmount": { ... },
    "totalScheduledTransferAmount": { ... }
  }
}
```

`totalAmount` can be **negative** — this is a valid state when card allocations exceed the current balance (temporary overdraft pending top-up).

## Example user prompts

- "What's the available wallet balance for each entity in the group?"
- "Give me a consolidated view of Spendesk cash across all entities"
- "Which entities have a negative wallet balance?"