> ## Documentation Index > Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt > Use this file to discover all available pages before exploring further. # Get Balances > GET /balances ## OpenAPI ````yaml GET /balances openapi: 3.1.0 info: title: ZoPay Connect API description: >- B2B partner API for crypto custody, deposits, and payouts. Authenticate every request with a Bearer token (``sk_live_…`` for production, ``sk_test_…`` for sandbox). version: v1 servers: - url: https://api.zopay.cash/connect/v1 description: Production - url: https://dev.api.zopay.cash/connect/v1 description: Development security: - BearerAuth: [] tags: - name: capabilities description: >- Static product catalog: which assets, networks, and fiat valuations this tenant can use. Poll on app startup to drive every UI surface (network pickers, fee warnings, fiat selection). - name: addresses description: >- Per-user deposit addresses. Mint with ``external_ref`` to attribute to one of your users; omit for a tenant-treasury (pooled) address. - name: payment-intents description: >- Single-use payment requests. Mint an intent for a specific amount + currency set; we expand it to per-network deposit addresses. Pass ``external_ref`` to attribute the intent to one of your users for downstream webhook reconciliation. - name: balances description: >- Per-user or tenant-wide balance snapshot with multi-fiat valuation (USD, PEN, EUR, MXN, ARS, COP, DOP). - name: transactions description: >- Unified ledger covering deposits, payouts, internal transfers, and (after Phase 4) conversions and ramps. - name: payouts description: >- Outbound money movement: get a signed quote, then execute it. Quote IDs are single-use and expire in 60s. - name: conversions description: '[Coming soon] Crypto-to-crypto conversions.' - name: ramps description: '[Coming soon] Fiat <-> crypto hosted-checkout sessions.' - name: webhooks description: '[Coming soon] Subscribe to event streams + replay past events.' - name: health description: >- Auth + connectivity probe. Use to validate your API key works before depending on a priced endpoint. - name: test-helpers description: >- Sandbox-only simulators. Let you exercise webhook handlers and downstream state transitions without real testnet activity. Routes return 404 to ``sk_live_…`` keys. paths: /balances: get: tags: - balances summary: Get balances (per-user when ``external_ref`` set; else tenant aggregate) description: >- Returns the user's per-asset balance lines when ``?external_ref=user_abc`` is set, or the tenant-aggregate balance across every Connect-provisioned user otherwise. Unknown refs return the empty-balance shape (NOT 404) -- partners legitimately probe refs before provisioning them. Per-line ``amount_`` fields are dynamic; only currencies enabled on the org appear. operationId: get_balances_balances_get parameters: - name: external_ref in: query required: false schema: anyOf: - type: string - type: 'null' description: >- The partner's user identifier. Omit to query the tenant-wide aggregate. title: External Ref description: >- The partner's user identifier. Omit to query the tenant-wide aggregate. responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/ConnectBalancesResponse' - $ref: '#/components/schemas/ConnectTenantBalancesResponse' title: Response Get Balances Balances Get '400': description: >- Invalid request. The body or query parameters failed validation. ``error.code`` names the specific failure (e.g. ``invalid_request``, ``catalog_invalid``, ``min_usdt_amount_requires_solana``); ``error.param`` names the offending field when applicable. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '401': description: >- Authentication failed. ``error.code`` distinguishes ``authentication_required`` (missing / malformed / unknown key) from ``expired_credential`` (key matched but past its ``expires_at``). Rotate the key in the admin panel for the latter. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '403': description: >- The key is valid but lacks permission for this endpoint. ``error.code`` is ``forbidden_scope`` when the key is missing a scope; ``account_pending_approval`` when the org is not yet active for Connect. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '404': description: >- Resource not found in this tenant. Same envelope shape is returned for genuinely-missing IDs and for cross-tenant accesses -- existence under other tenants is not leakable. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '409': description: >- Conflict. Most commonly ``idempotency_conflict`` -- the same ``Idempotency-Key`` was reused with a different body. Generate a fresh key or replay the original body. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '422': description: >- Validation failed. Runtime translates FastAPI / Pydantic validation errors into the same Connect envelope you see on 400s; this status is emitted when the request shape is structurally wrong (missing required field, wrong type). content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '429': description: >- Rate limited. Back off and retry. ``error.code`` is ``rate_limited``; per-key throughput is documented via ``rate_limit_rps`` on the API key. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '500': description: >- Internal server error. ``error.code`` is ``internal_error``. The request can usually be safely retried with the same ``Idempotency-Key``. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '501': description: >- Endpoint is declared in the router but its implementation has not shipped yet (``error.code = not_yet_available``). Pinned in the schema so SDK generators emit the endpoint with a typed error rather than skipping it. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' security: - BearerAuth: [] components: schemas: ConnectBalancesResponse: properties: external_ref: type: string title: External Ref description: The partner's user identifier, echoed back. balances: items: $ref: '#/components/schemas/ConnectBalanceLine' type: array title: Balances description: >- One row per enabled (asset, network) pair. Empty list when the user has no holdings, including the just-minted case where the external_ref was new to us. totals: additionalProperties: type: string type: object title: Totals description: >- Sum of line ``amount_`` values per enabled fiat currency. Keys are lowercase ISO codes (``usd``, ``pen``). Values are decimal strings; absent currencies indicate the per-line valuation was unavailable for at least one line (fail-closed total). valued_at: type: string format: date-time title: Valued At description: >- Server timestamp when the spot prices were fetched. Partners use this to decide whether to refresh. type: object required: - external_ref - valued_at title: ConnectBalancesResponse description: Per-user balance response (``external_ref`` was supplied). ConnectTenantBalancesResponse: properties: balances: items: $ref: '#/components/schemas/ConnectBalanceLine' type: array title: Balances totals: additionalProperties: type: string type: object title: Totals valued_at: type: string format: date-time title: Valued At type: object required: - valued_at title: ConnectTenantBalancesResponse description: |- Tenant-wide aggregate response (no ``external_ref`` supplied). Same line + totals shape as ``ConnectBalancesResponse``; only the top-level ``external_ref`` key is omitted. Treasury views use this — a partner sees their pooled holdings across every end user they've ever minted. ConnectErrorEnvelope: properties: error: $ref: '#/components/schemas/ConnectErrorBody' description: >- Error details. Always present on a non-2xx response from /connect/v1. type: object required: - error title: ConnectErrorEnvelope description: |- Top-level wrapper for every /connect/v1 failure response. Wire shape:: {"error": {"type": ..., "code": ..., "message": ..., ...}} The wrapper is intentional: it keeps error bodies syntactically distinct from success bodies, so polymorphic partner code paths that read the same JSON for both states can branch on the presence of the ``error`` key. ConnectBalanceLine: properties: asset: type: string title: Asset description: Asset code, uppercase (USDT, XAUT). amount: type: string title: Amount description: >- Holding amount in the asset's user-facing unit, as a decimal string. String, not number, to preserve precision across the JS Number boundary. additionalProperties: true type: object required: - asset - amount title: ConnectBalanceLine description: |- A single per-asset balance line. One row per asset. No per-network breakdown — balances are fungible across the networks an asset is available on, and the partner can derive per-network deposit/payout history from /transactions. This keeps /balances honest with the underlying data model (user_assets keyed by asset, not network) and avoids emitting per-network numbers that would all be identical. ``amount_`` fields (e.g. ``amount_usd``, ``amount_pen``) are populated dynamically based on the tenant's enabled fiat currencies. Pydantic's ``extra='allow'`` permits any ``amount_*`` key the service emits. ConnectErrorBody: properties: type: type: string title: Type description: >- Stripe-style error category. One of: ``invalid_request_error``, ``authentication_error``, ``not_found_error``, ``rate_limit_error``, ``idempotency_error``, ``api_error``. Stable across minor versions; branch on this for top-level error routing. examples: - invalid_request_error code: type: string title: Code description: >- Machine-stable identifier for the specific failure. More specific than ``type``. Examples: ``invalid_request``, ``authentication_required``, ``expired_credential``, ``forbidden_scope``, ``account_pending_approval``, ``resource_not_found``, ``idempotency_conflict``, ``rate_limited``, ``internal_error``, ``not_yet_available``. Match on ``code`` in your client's error handler -- never parse ``message``. examples: - authentication_required message: type: string title: Message description: >- Human-readable explanation. Safe to surface in your own UI but may be reworded between releases -- never branch on the string. examples: - >- Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_... doc_url: type: string title: Doc Url description: >- Link to docs explaining this ``code``. Constructed as ``https://docs.zopay.cash/errors/``. Surface this in support tickets so we can investigate without a round-trip. examples: - https://docs.zopay.cash/errors/authentication_required param: anyOf: - type: string - type: 'null' title: Param description: >- Names the offending input field when the error is input-shape-related (mostly ``invalid_request_error`` from 400 and 422). Absent on auth, scope, rate-limit, and internal errors. examples: - currencies type: object required: - type - code - message - doc_url title: ConnectErrorBody description: |- The ``error`` object inside every /connect/v1 failure response. Mirrors ``ConnectError.to_envelope()`` in ``app/api/connect/errors.py``. Field set is locked -- adding a new field is a partner-visible contract change and requires a coordinated docs + schema update. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Connect API key (sk_live_… or sk_test_…) description: >- Paste your Connect API key (sk_live_… for production, sk_test_… for sandbox) without the ``Bearer `` prefix. Mint and rotate keys from the admin panel. ````