REST API›Settle (Off Exchange)›Client Balances

GET

List client balances

This API call allows clients to get trading and allocated balances at BitGo for any connected trading partner. The trading balances are live data. The data under networkBalances are not the live balances at the partner, the live balances should be viewed on the partner's platform. networkBalances will only update as a result of allocations, deallocations, and settlement.

Error scenarios:

  • 400: Invalid Request Error

  • Occurs when the request parameters are invalid or malformed

  • Examples: Invalid UUID format for enterpriseId, invalid filter parameters, invalid pagination parameters, invalid connection or partner IDs

  • 401: Authentication Error

  • Occurs when the request is not authorized

  • Examples: Caller is not a member of the enterprise.

  • 403: Permission Denied Error

  • Occurs when the authenticated client doesn't have necessary permissions

  • Examples: Client doesn't have permission to view balances. Enterprise does not have OES license.

  • 404: Not Found Error

  • Occurs when the specified enterprise or resources cannot be found

  • Examples: Enterprise doesn't exist.

  • 500: Internal Server Error

  • Occurs when there's an unexpected server error processing the request

  • Examples: Database connection issues, transient network errors,

Requires access token scope: settlement_network_read

Path Params

  • enterpriseId string required
    The enterprise identifier of the client. This identifies the client enterprise that owns the allocation.

    at least 1 characters

Query Params

  • pageNumber string integer
    The page number (integer) you wish to fetch. When provided, the API will skip pageSize * pageNumber records. Page numbers are zero-based, so the first page is 0. If not provided, defaults to 0.
  • pageSize string
    The page size (integer) you wish to fetch. When provided, the API will return at most pageSize records per page. If not provided, a default page size defined by the server will be used.
  • connectionIds array of strings

    Optional array of connection IDs to filter by.

    If provided:

    • Only balances for connections with these specific IDs will be returned.
    • Useful for monitoring specific trading relationships or connections.
    • Can be used to focus on particular allocation targets.

    If omitted, results will include data for all your connections subject to other filters.

  • partnerIds array of strings

    Optional array of partner IDs to filter by.

    If provided:

    • Only balances for connections to partners with these IDs will be returned.
    • Useful for focusing on balances with specific partner organizations.
    • Can be used to monitor exposure to particular partners.

    If omitted, results will include data for connections to all partners.

Responses

200
OK

Response Body

object

  • clientId string required
    Unique identifier of the client whose balances are being returned. This UUID corresponds to your organization within the BitGo system.
  • balances map of objects required

    A record of account balances indexed by currency code.

    Each key in this record is a currency identifier (e.g., "ofcbtc", "ofceth", "ofcusdc"), and the corresponding value is an AccountBalance object containing the available and held amounts for that currency in base units.

    balances object
    • <key> object
      value object
      • available string required
        Amount of the specified currency available in the specified account. The amount is represented as a non-negative integer string in the currency's base units.
      • held string required
        Amount of the specified currency held (encumbered) in the specified account. The amount is represented as a non-negative integer string in the currency's base units.
  • networkBalances map of objects required

    Detailed information about balances across all your partner connections.

    This record contains:

    • Keys: Connection IDs that uniquely identify each connection
    • Values: Detailed information about the connection and its balances
    networkBalances object
    • <key> object
      Network account balance information formatted for client consumption. Contains details about a partner connection and associated balances.
      value object
      • partnerId string required
        Unique identifier of the partner associated with this connection. This UUID uniquely identifies the OES partner within the BitGo system.
      • partnersConnectionId string required
        External identifier of the connection as known by the partner system. This is the identifier that the partner uses to reference this connection.

        at least 1 characters

      • name string required
        Human-readable name of the connection. This is typically set during connection creation.

        at least 1 characters

      • partnerInstitutionIdentifier string required
        Institution identifier of the partner. This is typically set during connection creation to help identify the connection.

        at least 1 characters

      • balances map of objects required
        Balances available for this connection, indexed by currency code. Represents the funds that have been allocated to this connection and their status.
        balances object
        • <key> object
          value object
          • available string required
            Amount of the specified currency available in the specified account. The amount is represented as a non-negative integer string in the currency's base units.
          • held string required
            Amount of the specified currency held (encumbered) in the specified account. The amount is represented as a non-negative integer string in the currency's base units.
400
Bad Request
No response body
401
Unauthorized

Response Body

object

  • error string required
403
Forbidden

Response Body

object

  • error string required
404
Not Found

Response Body

object

  • error string required
500
Internal Server Error

Response Body

object

  • error string required