Ctrl+K

Deallocate Funds from Connection

post/api/network/v1/enterprises/{enterpriseId}/clients/connections/{connectionId}/deallocations

This API call allows clients to deallocate funds from a connected partner. A successful deallocation will unlock funds and ensure that they are available for actions (withdrawal/rebalancing) at BitGo. Note: Deallocations will happen synchronously and deallocated amounts can be viewed in the BitGo Application or via a balance endpoint.

Error scenarios:

  • 400: Invalid Request Error

  • Occurs when the request parameters are invalid or malformed.

  • Examples: Invalid UUID format for connectionId, invalid enterpriseId format, malformed request body, invalid signature format.

  • 401: Authentication Error

  • Occurs when the request is not authorized.

  • Examples: Caller is not a member of the enterprise.

  • 403: Permission Denied Error

  • Occurs when the authenticated client doesn't have necessary permissions.

  • Examples: Enterprise does not have OES license.

  • 404: Not Found Error

  • Occurs when the specified connection cannot be found.

  • Examples: Connection ID doesn't exist, connection doesn't belong to this client.

  • 422: Deallocation Error with Released Status

  • Occurs when the deallocation cannot be processed due to business rules.

  • Examples: Insufficient funds available for deallocation, connection is inactive, deallocation amount exceeds available balance.

  • 500: Internal Server Error or Reserved Deallocation

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

  • Examples: Database connection issues, transient network errors.

Path Parameters

  • enterpriseIdstringRequired
    The enterprise identifier of the client. This identifies the client enterprise that owns the connection.
    Min length: >= 1 characters
  • connectionIdstringRequired
    The unique identifier of the connection to deallocate from. This UUID uniquely identifies the connection between a client and a partner.

Request Body

amount object required
The amount to deallocate from the connection. Contains both the currency identifier and the quantity in base units.
currency string required
quantity string required
clientExternalId string required
External identifier provided by the client. Used for idempotence and correlation with client systems.
Min length: >= 1 characters
nonce string required
A unique nonce value used for cryptographic operations. This provides additional security for deallocation operations.
Min length: >= 1 characters
notes string
Optional notes provided by the client when creating the deallocation. Can contain additional context or information about the purpose of the deallocation.
Min length: >= 1 characters
payload string required
Payload formed by stringifying the object containing all other request properties. This includes: - amount: The amount to deallocate. - clientExternalId: Your unique identifier for this deallocation. - nonce: A unique value to prevent replay attacks. - notes: Optional notes about the deallocation. - connectionId: The connection to deallocate funds from. - enterpriseId: Your enterprise ID. The payload must be signed using your BitGo account's private key to create the signature parameter.
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 deallocation request
Min length: >= 1 characters

200 Response

One of
deallocation object required
The deallocation record in its cleared state. This contains all deallocation details with a status of 'cleared', indicating the allocation was successfully completed.
id string required
The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
amountOne ofrequired
The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.
connectionId string required
The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
clientExternalId string required
External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.
Min length: >= 1 characters
partnerExternalId string
External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.
Min length: >= 1 characters
initiatedBy string required
The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
Min length: >= 1 characters
notes string
Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.
Min length: >= 1 characters
createdAt string <date-time>required
The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
updatedAt string <date-time>required
The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
retriable boolean required
Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
Allowed value: false
status string required
Status of the allocation/deallocation. Possible values: - reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution. - cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation. - released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
Allowed value: cleared

400 Response

401 Response

error string required

403 Response

error string required

404 Response

error string required

422 Response

deallocation object required
The deallocation record in its released state. This contains all deallocation details with a status of 'released', indicating the allocation was not completed and funds were returned. The reason field will explain why the deallocation was released.
id string required
The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
amountOne ofrequired
The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.
connectionId string required
The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
clientExternalId string required
External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.
Min length: >= 1 characters
partnerExternalId string
External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.
Min length: >= 1 characters
initiatedBy string required
The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
Min length: >= 1 characters
notes string
Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.
Min length: >= 1 characters
createdAt string <date-time>required
The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
updatedAt string <date-time>required
The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
retriable boolean required
Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
Allowed value: false
status string required
Status of the allocation/deallocation. Possible values: - reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution. - cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation. - released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
Allowed value: released
reason string required
The reason that the allocation/deallocation is not cleared. Provides a descriptive explanation for why the allocation is in the reserved state. Will not be defined if the allocation is cleared.
Min length: >= 1 characters
error string required

500 Response

One of
error string required