REST API›Settle (Off Exchange)›Client Settlements & Transfers

GET

Get Client Settlement

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.

Requires access token scope: settlement_network_read

Path Params

  • enterpriseId string required
    The enterprise identifier of the client. This identifies the client enterprise making the API request.

    at least 1 characters

  • settlementId string required
    The unique identifier of the settlement to retrieve. This is a UUID that uniquely identifies the settlement record.

Query Params

  • currencies array of strings
    Filter by specific currencies. When provided, only settlement transfers involving these currencies will be included.
  • 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.

Responses

200
OK

Response Body

object

  • settlement object required
    The complete settlement object.
  • settlementTransfers array of objects required
    The settlement transfers associated with the settlement.
    settlementTransfers object
    • sourceTradingAccountId string
      The go account id of the source party.

      at least 1 characters

    • sourceNetworkAccountId string
      The network account id of the source party.
    • destinationTradingAccountId string
      The go account id of the destination party.

      at least 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.

      at least 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 of strings required
    • status string enum 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.
      pendingpending_onchainonchain_initiatedonchain_failedcompletedfailedrejecteddisputedpending_settlement_assignment
    • usdValue string or number nullable required
      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 enum 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).
      failedcompletedpendingrejected
    • settlementNotes string
      Optional notes for the settlement

      at least 1 characters

    • sourceClientName string
      The client name of the source party. Will be obfuscated if the source party is not the calling client.

      at least 1 characters

    • destinationClientName string
      The client name of the destination party. Will be obfuscated if the destination party is not the calling client.

      at least 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.

      at least 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.

      at least 1 characters

  • settlingDisputes array of objects required
    The disputes that are being settled as part of this settlement.
    settlingDisputes object
    • settledInSettlementId string required
    • disputeClosureId string required
    • disputeClosure object required
      disputeClosure object
      • id string required
        The unique identifier of the dispute closure.
      • closedBy string enum required

        Who closed the dispute.

        • admin - The dispute was closed by an admin.
        • client - The dispute was closed by a client.
        clientadmin
      • userId string required
        The id of the user who closed the dispute.

        at least 1 characters

      • notes string required
        notes entered by the user when closing the dispute.

        at least 1 characters

      • adjustedSettlementTransfers array of objects required
        The resulting settlement transfers generated when the dispute was closed
        adjustedSettlementTransfers object
        • id string required
          The unique identifier of the settlement transfer.
        • sourceTradingAccountId string required
          The go account id of the source party.

          at least 1 characters

        • destinationTradingAccountId string required
          The go account id of the destination party.

          at least 1 characters

        • destinationNetworkAccountId string required
          The network account id of the destination party.
        • disputeClosureId string required
          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.
        • currency string required
          The currency involved in the settlement movement.

          at least 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.
        • status string enum 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.
          pendingpending_onchainonchain_initiatedonchain_failedcompletedfailedrejecteddisputedpending_settlement_assignment
        • 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.
        • settlementId string
          The unique identifier of the settlement the settlement transfer is associated with. This is a UUID that uniquely identifies the settlement. Will only be undefined if the settlement transfer is in pending_settlement_assignment status.
        • sourceNetworkAccountId string
          The network account id of the source party.
      • createdAt string date-time required
        The date and time when the dispute closure was created.
      • status string enum required
        The status of the dispute closure review.
        pending_reviewapprovedrejected
      • adjustedTransfers map of strings required
        The adjusted transfers as a result of the dispute closure.
        adjustedTransfers object
        • <key> string
      • reviewedBy string
        The id of the admin who reviewed the dispute closure.

        at least 1 characters

      • reviewNotes string
        Any comments entered by the admin when reviewing the dispute closure.

        at least 1 characters

    • id string required
    • createdAt string date-time required
    • updatedAt string date-time required
    • connectionId string required
    • disputedSettlementId string required
    • userId string required

      at least 1 characters

    • expectedTransfers map of strings required
      expectedTransfers object
      • <key> string
    • retracted boolean required
    • settledInSettlementId string required
    • reason string

      at least 1 characters

    • retractedBy string

      at least 1 characters

    • retractedAt string date-time
    • disputeClosureId string required
    • retractedReason string

      at least 1 characters

  • settlementDisputes array of objects required
    The disputes that were raised on this settlement.
    settlementDisputes object
    • disputeClosure object
      disputeClosure object
      • Same shape as DisputeClosureOutput.
    • id string required
    • createdAt string date-time required
    • updatedAt string date-time required
    • connectionId string required
    • disputedSettlementId string required
    • userId string required

      at least 1 characters

    • expectedTransfers map of strings required
      expectedTransfers object
      • Same shape as ExpectedTransfersOutput.
    • retracted boolean required
    • settledInSettlementId string
    • reason string

      at least 1 characters

    • retractedBy string

      at least 1 characters

    • retractedAt string date-time
    • disputeClosureId string
    • retractedReason string

      at least 1 characters

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