Ctrl+K

Initiate partner settlement

post/api/network/v2/enterprises/{enterpriseId}/partners/settlements

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.

Path Parameters

  • enterpriseIdstringRequired
    The enterprise identifier of the partner. This identifies the partner enterprise making the API request.
    Min length: >= 1 characters

Request Body

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.
Min length: >= 1 characters
notes string
Optional notes about the settlement. Can contain additional context or information about the purpose of the settlement.
Min length: >= 1 characters
settlementAmountsOne ofrequired
dictionary<string, string>
nonce string required
A unique nonce value used for cryptographic operations. This provides additional security for settlement operations.
Min length: >= 1 characters
payload string required
Min length: >= 1 characters
signature string required
Min length: >= 1 characters
cutoffAt string <date-time>required
The date and time of the most recent trade being settled, represented in ISO 8601 format

200 Response

settlement object required
The initiated settlement object in it's pending state.
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.
settlingDisputes array[object] 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.
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.
disputed boolean
Whether or not a dispute was raised on this settlement.

400 Response

401 Response

error string required

403 Response

error string required

409 Response

error string required

422 Response

error string required

500 Response

error string required