Deallocate Funds from Connection

post

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

Requires access token scopes: settlement_network_read, settlement_network_write

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

enterpriseId

string

required

length ≥ 1

The enterprise identifier of the client.
This identifies the client enterprise that owns the connection.

connectionId

string

required

The unique identifier of the connection to deallocate from.
This UUID uniquely identifies the connection between a client and a partner.

Body Params

amount

object

required

The amount to deallocate from the connection.
Contains both the currency identifier and the quantity in base units.

clientExternalId

string

required

length ≥ 1

External identifier provided by the client.
Used for idempotence and correlation with client systems.

nonce

string

required

length ≥ 1

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

notes

string

length ≥ 1

Optional notes provided by the client when creating the deallocation.
Can contain additional context or information about the purpose of the deallocation.

payload

string

required

length ≥ 1

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.

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 deallocation request

Responses

200OK

400Bad Request

401Unauthorized

403Forbidden

404Not Found

422Unprocessable Entity

500Internal Server Error