Get Client Settlement

get/api/network/v1/enterprises/{enterpriseId}/clients/settlements/{settlementId}

This API call allows clients to get a list of settlement transactions for any connected network account, for a specific settlement. The settlement and its metadata will be returned along with all related settlement transfers in and out of the clients’ network accounts.

Error scenarios:

  • 400: Invalid Request Error

  • Occurs when the request parameters are invalid or malformed.

  • Examples: Invalid UUID format for settlementId, invalid enterpriseId format.

  • 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: Enterprise does not have OES license.

  • 404: Not Found Error

  • Occurs when the specified settlement cannot be found.

  • Examples: Settlement ID doesn't exist or the calling client isn't involved in the settlement.

  • 500: Internal Server Error

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

  • Examples: Database connection issues.

Path Parameters

  • enterpriseIdstringRequired
    The enterprise identifier of the client. This identifies the client enterprise making the API request.
    Min length: >= 1 characters
  • settlementIdstringRequired
    The unique identifier of the settlement to retrieve. This is a UUID that uniquely identifies the settlement record.

Query Parameters

  • currenciesarray[string]
    Filter by specific currencies. When provided, only settlement transfers involving these currencies will be included.
  • pageNumberstring<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.
  • pageSizestring
    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.

200 Response

settlementOne ofrequired
The complete settlement object.
id string required
The unique identifier of the settlement. This is a UUID that uniquely identifies the settlement record.
partnerId string required
The unique identifier of the partner the settlement is associated with. This is a UUID that uniquely identifies the partner.
externalId string required
External identifier provided by the partner when creating the settlement.
Min length: >= 1 characters
status string required
Allowed value: pending
settlementType string required
The type of settlement. Possible values are: - onchain: The settlement is on-chain. - offchain: The settlement is off-chain.
Allowed values: onchain offchain
reconciled boolean required
Whether or not the settlement is reconciled against trade data. Currently there are no reconciled settlements. This field is always false.
initiatedBy string required
Id of the user which initiated the settlement.
Min length: >= 1 characters
notes string
The notes associated with the settlement. This is a free-form text field that can contain any additional information about the settlement.
Min length: >= 1 characters
createdAt string <date-time>required
The date and time when the settlement was created. This is a timestamp in ISO 8601 format.
updatedAt string <date-time>required
The date and time when the settlement was last updated. This is a timestamp in ISO 8601 format.
rtId string
Routed transaction id associated with the settlement. This is a UUID that uniquely identifies the routed transaction. This field is only populated for on-chain settlements for partners with automation enabled.
lossSLAAlertSent boolean required
Whether or not an alert has been sent if loss settlement SLA is close to being breached. Only relevant for on-chain settlements.
gainSLAAlertSent boolean required
Whether or not an alert has been sent if gain settlement SLA is close to being breached. Only relevant for on-chain settlements.
cutoffAt string <date-time>
The date and time of the newest trade being settled in the partner system. This is a timestamp in ISO 8601 format. This field is only populated for dispute enabled partners.
disputed boolean
Whether or not a dispute was raised on this settlement.
settlementTransfers array[object] required
The settlement transfers associated with the settlement.
sourceTradingAccountId string
The go account id of the source party.
Min length: >= 1 characters
sourceNetworkAccountId string
The network account id of the source party.
destinationTradingAccountId string
The go account id of the destination party.
Min length: >= 1 characters
destinationNetworkAccountId string
The network account id of the destination party (if the destination party is a connection).
currency string required
The currency involved in the settlement movement.
Min length: >= 1 characters
quantity string required
The amount of currency being transferred in the settlement transfer. This is a non-zero value represented as a string. If the value is positive, that means funds were moved from the source account to the destination account. If the value is negative, that means funds were moved from the destination account to the source account.
txIds array[string] required
The transaction IDs associated with the settlement transfer. Only populated once the transfer is completed.
status string required
The status of the settlement transfer. Possible values and implications are: - pending: The transfer is pending and has not yet been processed. - pending_onchain: The transfer is pending on-chain movement (only relevant to on-chain settlements). - onchain_initiated: The transfer has been initiated on-chain (only relevant to on-chain settlements). - onchain_failed: The on-chain transfer has failed (only relevant to on-chain settlements). - completed: The transfer has been completed successfully. - failed: The transfer has failed. - rejected: The transfer has been rejected. - disputed: The transfer is disputed.
Allowed values: pending pending_onchain onchain_initiated onchain_failed completed failed rejected disputed pending_settlement_assignment
usdValueOne ofrequired
The USD value of the settlement transfer in cents. This is a non-negative value represented as a string.
settlementId string required
The unique identifier of the settlement the settlement transfer is associated with. This is a UUID that uniquely identifies the settlement.
disputeClosureId string
The unique identifier of the dispute closure the settlement transfer was created from. This is a UUID that uniquely identifies dispute closure if the transfer was created as a result of closing a dispute.
id string required
The unique identifier of the settlement transfer. This is a UUID that uniquely identifies the settlement transfer record.
createdAt string <date-time>required
The date and time when the settlement transfer was created. Represented as an ISO 8601 formatted date string.
updatedAt string <date-time>required
The date and time when the settlement transfer was last updated. Represented as an ISO 8601 formatted date string.
settlementStatus string required
The status of the settlement the settlement transfer is associated with. Possible values and implications are: - pending: The settlement is pending and has not yet been processed. - failed: The settlement has failed to process. This is a non-terminal state and should be retried. - completed: The settlement has been completed successfully. - rejected: The settlement has been rejected by a BitGo admin (only relevant to on-chain settlements).
Allowed values: failed completed pending rejected
settlementNotes string
Optional notes for the settlement
Min length: >= 1 characters
sourceClientName string
The client name of the source party. Will be obfuscated if the source party is not the calling client.
Min length: >= 1 characters
destinationClientName string
The client name of the destination party. Will be obfuscated if the destination party is not the calling client.
Min length: >= 1 characters
sourceConnectionName string
The name of the source connection (if the source party is a connection). Will be obfuscated if the source party is not the calling client.
Min length: >= 1 characters
destinationConnectionName string
The name of the destination connection (if the destination party is a connection). Will be obfuscated if the destination party is not the calling client.
Min length: >= 1 characters
settlingDisputes array[object] required
The disputes that are being settled as part of this settlement.
settledInSettlementId string required
disputeClosureId string required
disputeClosure object required
id string required
createdAt string <date-time>required
updatedAt string <date-time>required
connectionId string required
disputedSettlementId string required
userId string required
Min length: >= 1 characters
expectedTransfers dictionary<string, string> required
retracted boolean required
reason string
Min length: >= 1 characters
retractedBy string
Min length: >= 1 characters
retractedAt string <date-time>
retractedReason string
Min length: >= 1 characters
settlementDisputes array[object] required
The disputes that were raised on this settlement.
disputeClosure object
id string required
createdAt string <date-time>required
updatedAt string <date-time>required
connectionId string required
disputedSettlementId string required
userId string required
Min length: >= 1 characters
expectedTransfers dictionary<string, string> required
retracted boolean required
settledInSettlementId string
reason string
Min length: >= 1 characters
retractedBy string
Min length: >= 1 characters
retractedAt string <date-time>
disputeClosureId string
retractedReason string
Min length: >= 1 characters

400 Response

401 Response

error string required

403 Response

error string required

404 Response

error string required

500 Response

error string required