Initiate On-Chain Settlement

post

https://app.bitgo-test.com/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

enterpriseId

string

required

length ≥ 1

The enterprise identifier of the partner. This identifies the partner enterprise making the API request.

Body Params

externalId

string

required

length ≥ 1

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

length ≥ 1

Optional notes about the settlement. Can contain additional context or information about the purpose of the settlement.

settlementAmounts

object

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

length ≥ 1

A unique nonce value used for cryptographic operations. This provides additional security for settlement operations.

payload

string

required

length ≥ 1

The signed payload for the settlement request. This contains a stringified version of request body less the payload/signature.

signature

string

required

length ≥ 1

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

Responses

200OK

202Accepted

400Bad Request

401Unauthorized

403Forbidden

409Conflict

500Internal Server Error