GET

List partner balances

Lists all your OES balances. For use only by OES partners.

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
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 partner doesn't have necessary permissions
Examples: Partner doesn't have permission to view balances. Enterprise does not have OES license.
404: Not Found Error
Occurs when the specified enterprise cannot be found
Examples: Enterprise ID doesn't exist or doesn't belong to the partner
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 partner. This identifies the partner enterprise making the API request.

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.
partnerIds array of strings
Optional array of partner IDs to filter by.

If provided:
- Only balances for partners with these IDs will be returned.
- Only connections to these partners will be included.
- Useful when a partner has multiple partner entities and wants to filter results.
If omitted, results will include data for all partners the requester has access to.
clientIds array of strings
Optional array of client IDs to filter by.

If provided:
- Only balances for clients with these IDs will be returned.
- Useful for filtering results to specific client relationships.
If omitted, results will include data for all clients connected to the partner.
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 querying balances for specific connections.
If omitted, results will include data for all connections subject to other filters.
partnersConnectionIds array of strings
Optional array of partner connection IDs to filter by.

If provided:
- Only balances for connections with these partner-specific IDs will be returned.
- These are the IDs that partners use in their own systems to identify connections.
- Useful when partners want to look up balances using their own identifiers.
If omitted, results will include data for all connections subject to other filters.

Responses

200

Response Body

object

networkBalances map of objects required
Detailed information about balances across all client connections to this partner.

This record contains:
- Keys: Connection IDs that uniquely identify each connection.
- Values: Detailed information about the connection and its balances.
This provides a comprehensive view of client funds allocated to each connection and their current availability.
networkBalances object
- <key> object
  value object
  - clientId string required
    
    Unique identifier of the client associated with this connection. This UUID uniquely identifies the client organization within the BitGo system that has allocated funds to this connection.
  - partnerId string required
    
    Unique identifier of the partner associated with this connection. This UUID uniquely identifies your partner organization within the BitGo system.
  - partnersConnectionId string required
    
    External identifier of the connection as known by your partner system. This is your own identifier for this connection, which you can use to correlate with your internal systems.
    
    at least 1 characters
  - balances map of objects required
    
    The balances for this connection, indexed by currency code.
    
    This object contains:
    
    Keys: Currency identifiers in the partner's naming convention.
    
    Values: Balance information in base units, including available and held amounts.
    
    These balances represent funds that have been allocated by the client to this specific connection and are available for operations by the partner.
    
    balances object
    
    <key> object
    
    value object
    
    held string required
    
    Amount of the specified currency held (encumbered) in the account. The amount is represented as a non-negative integer or decimal string depending on partner configuration.
    
    available string required
    
    Amount of the specified currency available in the account. The amount is represented as a non-negative integer or decimal string depending on partner configuration.
balances map of objects
Information on the balances for the partner's own BitGo account.

This object, when present, contains:
- Keys: Currency identifiers (e.g., "BTC", "ETH", "USDC") in the partner's currency naming convention
- Values: Balance information in base units including available and held amounts for each currency
This allows partners to see their own BitGo account balances alongside client connection balances, providing a complete view of their financial position within the BitGo system.

Note: This field may be omitted if the partner doesn't have permission to view their own BitGo account balances.
balances object
- <key> object
  value object
  - held string required
    
    Amount of the specified currency held (encumbered) in the account. The amount is represented as a non-negative integer or decimal string depending on partner configuration.
  - available string required
    
    Amount of the specified currency available in the account. The amount is represented as a non-negative integer or decimal string depending on partner configuration.

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

curl --request GET \ --url 'https://app.bitgo-test.com/api/network/v1/enterprises/enterpriseId/partners/balances&pageNumber=string&pageSize=string&partnerIds=&clientIds=&connectionIds=&partnersConnectionIds=' \ --header 'accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

const url = 'https://app.bitgo-test.com/api/network/v1/enterprises/enterpriseId/partners/balances&pageNumber=string&pageSize=string&partnerIds=&clientIds=&connectionIds=&partnersConnectionIds='; const options = {method: 'GET', headers: {accept: 'application/json', 'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}}; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));

require 'uri' require 'net/http' url = URI("https://app.bitgo-test.com/api/network/v1/enterprises/enterpriseId/partners/balances&pageNumber=string&pageSize=string&partnerIds=&clientIds=&connectionIds=&partnersConnectionIds=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["accept"] = 'application/json' request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN' response = http.request(request) puts response.read_body

<?php require_once('vendor/autoload.php'); $client = new \GuzzleHttp\Client(); $response = $client->request('GET', 'https://app.bitgo-test.com/api/network/v1/enterprises/enterpriseId/partners/balances&pageNumber=string&pageSize=string&partnerIds=&clientIds=&connectionIds=&partnersConnectionIds=', [ 'headers' => [ 'accept' => 'application/json', 'Authorization' => 'Bearer YOUR_ACCESS_TOKEN', ], ]); echo $response->getBody();

import requests url = "https://app.bitgo-test.com/api/network/v1/enterprises/enterpriseId/partners/balances&pageNumber=string&pageSize=string&partnerIds=&clientIds=&connectionIds=&partnersConnectionIds=" headers = { "accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" } response = requests.get(url, headers=headers) print(response.text)

{ "networkBalances": { "key": { "clientId": "string", "partnerId": "string", "partnersConnectionId": "string", "balances": { "key": { "held": "string", "available": "string" } } } }, "balances": { "key": { "held": "string", "available": "string" } } }