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

POST

Perform Partner Settlement

Partner route to perform a settlement. This endpoint allows partners without disputes enabled to create new settlements between client accounts, transferring funds according to the specified amounts.

Please note that this endpoint cannot be used by partners with disputes enabled, instead use the V2 Settlement endpoint. This is because dispute enabled partners must have an asyncronous settlement process to allow clients time to review the settlement and reconcile liabilities agains their trading activity on your platform. In the event that you cal this endpoint and you have disputes enabled, you will recieve a 403 response.

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 enabled for disputes, 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.

  • 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

    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

Responses

200
OK

Response Body

object

  • settlement object required
    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.

      at least 1 characters

    • status string enum required
      completed
    • 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.
    • finalizedAt string date-time required
    • 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.
400
Bad Request
No response body
401
Unauthorized

Response Body

ONE OF

  • settlement object required

    ONE OF

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

Response Body

object

  • error string required
409
Conflict

Response Body

object

  • error string required
500
Internal Server Error

Response Body

ONE OF

  • settlement object required

    ONE OF

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