Ctrl+K

Initiate On-Chain Settlement

post/api/network/v1/enterprises/{enterpriseId}/partners/settlements/onchain

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.

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
settlementAmounts dictionary<string, object> required
The settlement amounts to be processed. Only exchange-style settlements (where the exchange is the source) are supported for on-chain settlements.
dictionary<string, string>
For mapped settlement amounts where the amount will always be a bigint. This ensures consistent handling of large monetary values in settlements.
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
The signed payload for the settlement request. This contains a stringified version of request body less the payload/signature.
Min length: >= 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
Min length: >= 1 characters

200 Response

settlementOne ofrequired
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.
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 Response

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

401 Response

error string required

403 Response

error string required

409 Response

error string required

500 Response

error string required