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

POST

Initiate partner settlement

Used by dispute enabled exchange partners to stage a settlement for connected clients.

This endpoint will:

  1. Authenticate the request by verifying the payload and signature provided.
  2. Create entities: a. Create the settlement entity b. Map provided settlement amounts to settlement transfer records for execution.
  3. Assign closed, unassigned disputes from prior settlements to this settlement a. Pull in any adjustedSettlementTransfers from said disputes. b. Update the settledInSettlementId on said disputes.
  4. Verify the relevant connection balances against liabilities based on provided settlementAmounts and assigned settlement transfers from disputes being assigned.
  5. Notify connection owners of a new settlement.
  6. Queue an event to finalize the settlement once the dispute window ends.

This endpoint is idempotent and can safely be called again with the same exact request body without worrying about creating multiple settlements.

Please note that provided settlement amounts should be based solely on new trading activity that was not included in the last settlement. Instructions from closed, unsettled disputes should not be included in the calculation of settlement instructions on the Settlement will be processed asynchronously once initiated, after dispute / top up window have elapsed.

  • Error scenarios:

  • 400: Invalid Request Error

  • Occurs when the request parameters are invalid or malformed.

  • Examples: Invalid format for settlement amounts, missing required fields, invalid signature.

  • 401: Authentication Error or Incomplete Settlement

  • Occurs when the request is not authorized or cannot be completed immediately.

  • Examples: Caller is not a member of the enterprise, signature verification failed.

  • 403: Permission Denied Error

  • Occurs when the authenticated partner doesn't have necessary permissions.

  • Examples: Enterprise does not have OES license, partner is inactive

  • 409: Conflict Error

  • Occurs when the request conflicts with current state.

  • Examples: Settlement already exists with the same externalId and different properties.

  • 422: Unprocessable Content

  • Occurs when the request is authenticated and permitted but is unable to be processed.

  • Examples: the liabilities for one or more connection exceed their allocated balance.

  • 500: Internal Server Error or Incomplete Settlement

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

  • Examples: Database connection issues, settlement initiated but not completed due to transient errors.

Requires access token scopes: settlement_network_read, settlement_network_write

Path Params

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

    at least 1 characters

Body Params

object

  • externalId string required
    External identifier for the settlement request. This should be unique for each settlement request and is used for idempotence and correlation with partner systems.

    at least 1 characters

  • notes string
    Optional notes about the settlement. Can contain additional context or information about the purpose of the settlement.

    at least 1 characters

  • settlementAmounts object required

    ONE OF

    • <key> map of strings
      value object
      • <key> string
        For unmapped settlement amounts where the amount can be either BigNumberFromString or BigIntFromString. This provides flexibility in how monetary values are represented in settlement requests.
  • nonce string required
    A unique nonce value used for cryptographic operations. This provides additional security for settlement operations.

    at least 1 characters

  • payload string required

    at least 1 characters

  • signature string required

    at least 1 characters

  • cutoffAt string date-time required
    The date and time of the most recent trade being settled, represented in ISO 8601 format

Responses

200
OK

Response Body

object

  • settlement object required
    The initiated settlement object in it's pending state.
    settlement object
    • cutoffAt string date-time required
      The datetime provided by the partner representing the timestamp of the most recent trade being settled.
    • settlingDisputes array of objects required
      Array of disputes that were closed and not yet assigned at the time the request was first received. These disputes are assigned to the settlement and their associated adjustedSettlementTransfers will be executed with this settlement regardless of whether or not the associated client(s) dispute.
      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

    • 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.

      at least 1 characters

    • status string enum required
      pending
    • settlementType string enum required

      The type of settlement. Possible values are:

      • onchain: The settlement is on-chain.
      • offchain: The settlement is off-chain.
      onchainoffchain
    • 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.

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

      at least 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 required
      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.
400
Bad Request
No response body
401
Unauthorized

Response Body

object

  • error string required
403
Forbidden

Response Body

object

  • error string required
409
Conflict

Response Body

object

  • error string required
422
Unprocessable Entity

Response Body

object

  • error string required
500
Internal Server Error

Response Body

object

  • error string required