Sign in
Partner Settlements & Transfers

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

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

Path parameters

enterpriseIdstring required

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

Request body

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

notesstring

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

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

noncestring required

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

payloadstring required

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

signaturestring 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

OK

Changes

No recorded changes to this endpoint across all 17 revisions of this API.