# Deallocate Assets

Source: https://developers.bitgo.com/docs/oes-partner-deallocate

## 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 application or programmatically.

## Prerequisites

* [Get Started](/docs/get-started-intro) - Ensure your access token has the following permissions:
    * `Settlement Network - Read`
    * `Settlement Network - Write`
* [Request Signing and Verification](/docs/oes-partner-signature)
* [Activate Client Connections](/docs/oes-partner-connect)
* [Allocate Assets](/docs/oes-partner-allocate)

## 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 assets should be reserved.
* Respond with a `200`, idempotently, if the deallocation is already cleared. No additional assets 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 you rejected the deallocation prior.
  * Return the previously approved state, if you approved the deallocation prior.
* Be able to guard against racing requests.
* Include the `deallocationId` and `allocationId` as part of a one unified unique index.

#### Request Headers

| Header | Type | Description |
| :---- | :---- | :---- |
| `X-BitGo-Signature` | string | The signature BitGo provides using a private/public key pair. |

##### Request Body

| Parameter | Type | Description |
| :---- | :---- | :---- |
| `deallocationId` | UUID | The BitGo ID for the deallocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to deallocate. |
| `clientId` | UUID | The BitGo ID for the user on your system. |
| `connectionId` | UUID | The ID of the connection. |
| `partnersConnectionId` | string | The ID of your partner account tied to the connection. |
| `partnersClientId` | string | The ID of the user in your system. |

#### 200 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| `deallocationId` | UUID | The BitGo ID for the deallocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to deallocate. |
| `clientId` | UUID | The BitGo ID for the user on your system. |
| `connectionId` | UUID | The ID of the connection. |
| `partnersClientId` | string | The ID for the user on your system. |
| `partnersConnectionId`| string | The ID of your partner account tied to the connection. |
| `partnersDeallocationId` | string | The ID for the deallocation on your system. |
| `rejectionReason?` | string | The reason for a rejection. The standardized values are: “Unsupported currency” “Insufficient funds” |

> 📘 **Note**
>
> BitGo displays the `rejectionReason?` to the user who requested the deallocation.

#### 400/401/409/500 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| error | string | A description of the error. |

### 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.
* 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 releasing or clearing a cleared deallocation again.
* Be able to guard against racing requests.

#### Request Headers

| Header | Type | Description |
| :---- | :---- | :---- |
| `X-BitGo-Signature` | string | The signature BitGo provides using a private/public key pair. |

#### 200 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| `deallocationId` | UUID | The BitGo ID for the deallocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to deallocate. |
| `clientId` | UUID | The BitGo ID for the user on your system. |
| `connectionId` | UUID | The ID of the connection. |
| `partnersClientId` | string | The ID for the user on your system. |
| `partnersConnectionId` | string | The ID of your partner account tied to the connection. |
| `partnersDeallocationId` | string | The ID for the deallocation on your system. |

#### 400/401/409/500 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| error | string | A description of the error. |

#### 404 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| error | string | Must contain the standardized error description: "Deallocation not found" |

### 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.
* 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 releasing or clearing a cleared deallocation again.
* Be able to guard against racing requests.

#### Request Headers

| Header | Type | Description |
| :---- | :---- | :---- |
| `X-BitGo-Signature` | string | The signature BitGo provides using a private/public key pair. |

#### 200 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| `deallocationId` | UUID | The BitGo ID for the deallocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to deallocate. |
| `clientId` | UUID | The BitGo ID for the user on your system. |
| `connectionId` | UUID | The ID of the connection. |
| `partnersClientId` | string | The ID for the user on your system. |
| `partnersConnectionId`| string | The ID of your partner account tied to the connection. |
| `partnersDeallocationId` | string | The ID for the deallocation on your system. |

#### 400/401/409/500 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| error | string | A description of the error. |

#### 404 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| error | string | Must contain the standardized error description: "Deallocation not found" |

## 1. Reserve Assets

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

```json API
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
    "partnersClientId": string
}
```

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

```json JSON
{
    "deallocationId": UUID
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": string
    "partnersClientId": string
    "partnersDeallocationId": string
    "rejectionReason?": string
}
```

## 2. Clear Assets

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

```json API
PUT /bitgo/v1/deallocation/{deallocationId}/clear
```

Clients can now trade their allocated assets on your platform.

```json JSON
{
    "deallocationId": UUID
    "partnersDeallocationId": string
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": string
    "partnersClientId": string
}
```

## 3. Report Deallocation Status to BitGo (Async Partners Only)

>Endpoint: [Update Partner Deallocations](/reference/v1partnerdeallocationsputroute)

This step applies only to partners with **async deallocations** enabled. In an async flow, your endpoint in Step 1 returns a `reserved` state immediately, and BitGo does not call `/clear` or `/release`. Instead, your platform processes the deallocation asynchronously and reports the final status back to BitGo using this endpoint.

Call this endpoint once you process the deallocation on your platform:

* Set `status` to `cleared` when you debit the client account and confirm the deallocation.
* Set `status` to `released` when the deallocation cannot be processed and must be reversed. Include `rejectReason` when releasing.

> 📘 **Note**
>
> When you report the status back to BitGo the deallocation reaches a terminal state and can't be updated further.

The request body must be cryptographically signed. See [Request Signing and Verification](/docs/oes-partner-signature).

```shell cURL
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X PUT \
  https://app.bitgo-test.com/api/network/v1/enterprises/$ENTERPRISE_ID/partners/deallocations \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "deallocationId": "<bitgo-deallocation-uuid>",
    "status": "cleared",
    "amount": {
      "currency": "ofcbtc",
      "quantity": "100000"
    },
    "clientId": "<bitgo-client-uuid>",
    "connectionId": "<bitgo-connection-uuid>",
    "partnersClientId": "<your-client-id>",
    "partnersConnectionId": "<your-connection-id>",
    "partnersDeallocationId": "<your-deallocation-id>",
    "nonce": "<unique-nonce>",
    "payload": "<stringified payload>",
    "signature": "<signature>"
  }'
```

To release a deallocation, set `status` to `released` and include a `rejectReason`:

```shell cURL
curl -X PUT \
  https://app.bitgo-test.com/api/network/v1/enterprises/$ENTERPRISE_ID/partners/deallocations \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "deallocationId": "<bitgo-deallocation-uuid>",
    "status": "released",
    "rejectReason": "Insufficient funds",
    "amount": {
      "currency": "ofcbtc",
      "quantity": "100000"
    },
    "clientId": "<bitgo-client-uuid>",
    "connectionId": "<bitgo-connection-uuid>",
    "partnersClientId": "<your-client-id>",
    "partnersConnectionId": "<your-connection-id>",
    "partnersDeallocationId": "<your-deallocation-id>",
    "nonce": "<unique-nonce>",
    "payload": "<stringified payload>",
    "signature": "<signature>"
  }'
```

#### Step Result

```json JSON
{
  "deallocationId": "<bitgo-deallocation-uuid>",
  "amount": {
    "currency": "ofcbtc",
    "quantity": "100000"
  },
  "clientId": "<bitgo-client-uuid>",
  "connectionId": "<bitgo-connection-uuid>",
  "partnersClientId": "<your-client-id>",
  "partnersConnectionId": "<your-connection-id>",
  "partnersDeallocationId": "<your-deallocation-id>"
}
```

## Next

* [Create Settlements](/docs/oes-partner-settlements)
* [View Go Network Details](/docs/oes-partner-view-details)