---
title: "Initiate On-Chain Settlement"
method: POST
path: "/api/network/v1/enterprises/{enterpriseId}/partners/settlements/onchain"
tags: ["Partner Settlements & Transfers"]
---

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

**Requires access token scopes:** `settlement_network_read`, `settlement_network_write`

## Path parameters

- `enterpriseId` string, required

## Request body

- 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.
  - `notes` string — Optional notes about the settlement. Can contain additional context or information about the purpose of the settlement.
  - `settlementAmounts` PartySettlementAmountsRecord, required — Maps destination connection IDs to currency amounts for settlement. Record<Party (destination) connectionId, Record<Currency, Amount (bigint)>> Used for exchange-style settlements, where the exchange is always the source and client owned connections are the destination. Each entry maps a destination connection ID to the currency amounts being settled to that connection.
  - `nonce` string, required — A unique nonce value used for cryptographic operations. This provides additional security for settlement operations.
  - `payload` string, required — The signed payload for the settlement request. This contains a stringified version of request body less the payload/signature.
  - `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

## Response `200`

OK

- V1SettlementPayload
  - `settlement` union, required
    - V1PendingSettlementOutput
      - `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.
      - `status` 'pending', required
      - `settlementType` 'onchain' | 'offchain', required
      - `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.
      - `notes` string — The notes associated with the settlement. This is a free-form text field that can contain any additional information about the settlement.
      - `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.
    - V1FailedSettlementOutput
      - `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.
      - `reason` string, required
      - `status` 'failed', required
      - `settlementType` 'onchain' | 'offchain', required
      - `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.
      - `notes` string — The notes associated with the settlement. This is a free-form text field that can contain any additional information about the settlement.
      - `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.
    - V1CompleteSettlementOutput
      - `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.
      - `status` 'completed', required
      - `settlementType` 'onchain' | 'offchain', required
      - `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.
      - `notes` string — The notes associated with the settlement. This is a free-form text field that can contain any additional information about the settlement.
      - `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.
    - V1RejectedSettlementOutput
      - `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.
      - `reason` string, required
      - `status` 'rejected', required
      - `settlementType` 'onchain' | 'offchain', required
      - `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.
      - `notes` string — The notes associated with the settlement. This is a free-form text field that can contain any additional information about the settlement.
      - `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.

## Other responses

- `202` — Accepted
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `500` — Internal Server Error

---

[API](https://skmtc.net/bitgo/apis/bitgo-api.md) · [All operations](https://skmtc.net/bitgo/apis/bitgo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitgo/bitgo-api/revisions/e445c15e5bee/schema)