---
title: "Get Unified Balance"
method: GET
path: "/v2/wallet/unified-balance"
tags: ["v2 - Wallet"]
---

# Get Unified Balance

`GET /v2/wallet/unified-balance`

## Request

- Base URL: `https://api.jubjubapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.jubjubapp.com/v2/wallet/unified-balance`
- Auth: HTTP bearer

Aggregate the user's spendable USDC: smart wallet balance + every
catalogue's claimable amount. Used by the frontend to render a single
balance number and to drive silent auto-claim before a spend.

## Headers

- `Authorization` string
- `X-JubJub-Service-Key` string
- `X-JubJub-Agent-Key` string
- `X-JubJub-Platform-Key` string
- `Origin` string
- `Referer` string
- `X-JubJub-Trial-Token` string

## Response `200`

Successful Response

- UnifiedBalanceResponse
  - `total_usdc` number, required: wallet_balance + sum(pending_in_catalogues), in DECIMAL USDC (4.25 means $4.25), the same unit as every other total_usdc. This is the single number the frontend displays as the user's balance.
  - `total_micro` integer: The same total in raw USDC units (6 decimals): 4250000 == $4.25. wallet_balance and pending_in_catalogues[].amount are raw too.
  - `wallet_balance` integer, nullable: USDC.balanceOf(wallet) in raw units, or NULL when that read failed. Null is not zero: a zero here would be a specific, spendable-looking claim about a balance nobody could read. Check `wallet_balance_read` before treating it as a number.
  - `wallet_balance_read` boolean: False when USDC.balanceOf failed. `total_usdc` then excludes the wallet leg entirely and is a floor, not a total.
  - `pending_in_catalogues` PendingCatalogueEntry[]: Per-catalogue claimable breakdown: unclaimed revenue sitting in catalogue contracts, spendable only after a catalogue.claim(). The frontend renders the sum as the claimable figure and uses the per-entry addresses to target claim() calls. Entries with a zero amount are omitted.
    - `catalogue_address` string, required: Catalogue contract address
    - `amount` integer, required: Claimable amount in raw USDC units (6 decimals)
  - `partial` boolean: True when EITHER leg was incomplete — the wallet balance could not be read, or one or more catalogues were skipped. A consumer summing `total_usdc` has no other way to know something is missing. Auto-claim in particular must not treat a partial picture as a complete one: claiming against it is acting on a number known to be short.
  - `skipped_catalogues` object[]: Catalogues left out of the sum, each with the reason. Populated for codeless addresses (pre-cutover leftovers); a live catalogue that fails to answer produces a 503 instead of an entry here.
  - `wallet_address` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/jubjubapp/apis/jubjub-api.md) - [All operations](https://skmtc.dev/jubjubapp/apis/jubjub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jubjubapp/apis/jubjub-api/revisions/353157b296f2?raw)