Deallocate Assets

Overview

Clients can initiate deallocations of their assets from their account on your platform to their Go Network account. Deallocating assets unlocks them at BitGo, making them available for clients to do any other actions, such as rebalancing or withdrawing. Deallocations occur synchronously. You can view deallocated balances from the BitGo web UI or programmatically.

Prerequisites

• Get Started - Ensure your access token has the following permissions:
  • Settlement Network - Read
  • Settlement Network - Write
• Request Signing and Verification
• Activate Client Connections
• Allocate Assets

API Specifications

Use the following specifications to build out deallocation endpoints. Bitgo will send requests to these endpoints to process deallocations.

Deallocations

Route: POST /bitgo/v1/deallocations

This endpoint must:

• Respond with a 200 if the deallocation is already released. Additional funds should be reserved.
• Respond with a 200, idempotently, if the deallocation is already cleared. No additional funds should be reserved.
• Put a hold on the amount that can be cleared (confirmed) or canceled (released) using the PUT endpoint.
• Take a deallocationId in the event of a retry, so that you don't act on the same deallocation twice. The endpoint should be idempotent.
  • Return the previously rejected state, if the deallocation was rejected prior.
  • Return the previously approved state, if the deallocation was approved prior.
• Be able to guard against racing requests.
• Include the deallocationId and allocationId as part of a one unified unique index.

Request Headers

Request Body

200 Response

400/401/409/500 Response

Clear deallocation

Route: PUT /bitgo/v1/deallocation/:deallocationId/clear

This endpoint must:

• Issue a 404 response, stating Deallocation not found, if you have no record of the deallocation or allocation in your system. BitGo checks for this response during the failure remediation process.
• Issue a 409 response if BitGo is attempting to update status to cleared, on an already released deallocation.
• Issue a 404 response if BitGo calls a put on a deallocation that isn’t in the reserved status on your system.
• Include the deallocationId and allocationId as part of a one unified and unique index.
• Take a deallocationId in the event of failure remediation, so that you don't act on the same deallocation twice. The endpoint should be idempotent.
• Be able to reserve and clear a released deallocation.
• Prevent a cleared deallocation from being released or cleared again.
• Be able to guard against racing requests.

Request Headers

200 Response

400/401/409/500 Response

404 Response

Release deallocation

Ordering a release on your system only occurs if a BitGo admin must perform a full, manual reversal of a deallocation.

Route: PUT /bitgo/v1/deallocation/:deallocationId/release

This endpoint must:

• Issue a 404 response, stating Deallocation not found, if you have no record of the deallocation or allocation in your system. BitGo checks for this response during the failure remediation process.
• Issue a 409 response, if BitGo is attempting to update status to cleared, on an already released deallocation.
• Issue a 404 response, if BitGo calls a put on a deallocation that isn’t in the reserved status on your system.
• Include the deallocationId and allocationId as part of a one unified and unique index.
• Take an deallocationId in the event of failure remediation, so that you don't act on the same deallocation twice. The endpoint should be idempotent.
• Be able to reserve and clear a released deallocation.
• Prevent a cleared deallocation from being released or cleared again.
• Be able to guard against racing requests.

Request Headers

200 Response

400/401/409/500 Response

404 Response

1. Reserve Assets

BitGo sends you the following request for each client-initiated deallocation:

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
POST /bitgo/v1/deallocations

Request Body
{
    "deallocationId": UUID
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: string }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": NonEmptyString
    "partnerClientId": string
}

You put the requested amount into a RESERVED state that you can then credit (confirm or clear) once the assets are released in the next step.

Copy code block
1
2
3
4
5
6
7
8
9
10
11
{
    "deallocationId": UUID
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": string
    "partnerClientId": string
    "partnerDeallocationId": string
    "rejectionReason?": string
}

2. Clear Assets

BitGo sends you the following PUT call, notifying you that it's now safe to credit the client's account with the reserved assets. This enables clients to withdraw their deallocated assets from your platform.

Copy code block
1
PUT /bitgo/v1/deallocation/{deallocationId}/clear

Clients can now trade their allocated assets on your platform.

Copy code block
1
2
3
4
5
6
7
8
9
10
{
    "deallocationId": UUID
    "partnerDeallocationId": string
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": string
    "partnerClientId": string
}

Next

• Create Settlements
• View Go Network Details