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

POST

Initiate On-Chain Settlement

Partner route to initiate an on-chain settlement. This endpoint allows partners to create settlements that will be processed on a blockchain, with multi-phase settlement flow.

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

  • Occurs when the request is not authorized.

  • 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, on-chain settlements not enabled.

  • 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

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

  • Examples: Database connection issues.

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 map of objects required
    The settlement amounts to be processed. Only exchange-style settlements (where the exchange is the source) are supported for on-chain settlements.
  • 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
    The signed payload for the settlement request. This contains a stringified version of request body less the payload/signature.

    at least 1 characters

  • signature string required

    Digital signature of the payload parameter.

    This signature:

    • Must be created using your BitGo account's private key
    • Verifies that the request is authentic and hasn't been tampered with
    • Provides non-repudiation for the allocation request

    at least 1 characters

Responses

200
OK

Response Body

object

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

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
      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.
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
500
Internal Server Error

Response Body

object

  • error string required