Get Bulk Wallet Balances

Returns cash balances across up to 100 connected users in one call, one result per target.

Requirements

Authorization: Basic <API_KEY> (your application API key)
The bulk API capability on your application
The LIST_PAYMENT scope on each target user’s grant

Failures are reported per target and never fail the whole request. See Bulk API Overview for the targeting model and error codes.

Query

query GetBulkBalances($targetSpec: BulkTargetSpecInput!) {
  getBulkBalances(targetSpec: $targetSpec) {
    targetCount
    successCount
    failureCount
    results {
      externalReferenceId
      accountId
      success
      error { code message }
      balances {
        userCashBalanceId
        nickname
        status
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        createdAt
      }
    }
  }
}

Variables — selected users

{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] }
}

Variables — all connected users

{
  "targetSpec": { "mode": "ALL_CONNECTED" }
}

Response

{
  "data": {
    "getBulkBalances": {
      "targetCount": 2,
      "successCount": 1,
      "failureCount": 1,
      "results": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "success": true,
          "error": null,
          "balances": [
            {
              "userCashBalanceId": "ucb-1",
              "nickname": "Main account",
              "status": "ACTIVE",
              "totalCashBalance": "125.50",
              "availableCashBalance": "100.00",
              "lifetimeCashBalance": "500.00",
              "createdAt": "2026-01-01T00:00:00.000Z"
            }
          ]
        },
        {
          "externalReferenceId": "your-user-002",
          "accountId": "a90d…",
          "success": false,
          "error": {
            "code": "INSUFFICIENT_SCOPE",
            "message": "The user has not granted the scopes this operation requires. Missing scopes: LIST_PAYMENT."
          },
          "balances": null
        }
      ]
    }
  }
}

Arguments

Argument	Type	Description
`targetSpec.mode`	`BulkTargetMode!`	`ALL_CONNECTED` or `SELECTED`.
`targetSpec.targets`	`[String!]`	`externalReferenceId`s to target. Required for `SELECTED`; ignored for `ALL_CONNECTED`. Duplicates removed; result order follows this list. Max 100.

Response fields

Field	Description
`results[].success`	Whether balances were returned for this target.
`results[].error`	Present when `success` is `false`. See error codes in the Overview.
`results[].balances`	The user’s cash balances. Restricted to permitted spend accounts when the grant is spend-account-scoped.
`targetCount` / `successCount` / `failureCount`	Request-level summary.

A target whose grant is scoped to specific spend accounts returns only those balances — automatically, with no extra parameters.

​Requirements

​Query

​Variables — selected users

​Variables — all connected users

​Response

​Arguments

​Response fields

Requirements

Query

Variables — selected users

Variables — all connected users

Response

Arguments

Response fields