# Allocate Assets

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

## Overview

Clients can allocate assets from their Go Network account to their account on your platform. When clients allocate assets, BitGo sends you an allocation request that includes an allocation ID.

Using the allocation ID, you must respond to allocation requests with a reserved or rejected result:

* If no allocation exists, create a new reserved allocation in the client's account on your platform.
* If an allocation already exists or you rejected it, return the current status.
* If an allocation is already cleared or released, return a conflict error.

> 📘 **Note**
>
> This endpoint doesn't credit the client account. It only creates a reserved allocation within your platform that can be cleared (confirmed) by BitGo during deallocation or trade settlement.

## Prerequisites

* [Get Started](/docs/get-started-intro) - Ensure your access token has the following permissions:
  * `Settlement Network - Read`
  * `Settlement Network - Write`
* [Generate Signature](/docs/oes-partner-signature)
* [Activate Client Connections](/docs/oes-partner-connect)

## API Specifications

Use the following to build endpoints that BitGo can send requests to for processing allocations.

### Allocations

Route: `POST /bitgo/v1/allocations`

This endpoint must:

* Respond with a `200` if the allocation is already released. Additional assets should be reserved.
* Respond with a `200`, idempotently, if the allocation is already cleared. No additional assets should be reserved.
* Put the amount requested in a reserved state that can be credited (confirmed and cleared) or canceled (released) using the `PUT` endpoint.
* Take an `allocationId` in the event of a retry, so that you don't act on the same allocation twice. The endpoint should be idempotent.
  * Return the previously rejected state, if you rejected the allocation prior.
  * Return the previously approved state, if you approved the allocation prior.
* 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. |

#### Request Body

| Parameter | Type | Description |
| :---- | :---- | :---- |
| `allocationId` | UUID | The BitGo ID for the allocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to allocate. |
| `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 |
| :---- | :---- | :---- |
| `allocationId` | UUID | The BitGo ID for the allocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to allocate. |
| `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. |
| `partnersAllocationId` | string | The ID for the allocation on your system. |
| `rejectionReason?` | string | The reason for a rejection. The standardized value is “Unsupported currency” |

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

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

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

### Clear allocation

Route: `PUT /bitgo/v1/allocation/:allocationId/clear`

This endpoint must:

* Issue a `404` response, stating `Allocation not found`, if you have no record of the allocation or deallocation 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 allocation.
* Issue a `404` response if BitGo calls a put on an allocation that isn’t in the reserved status on your system.
* Take an `allocationId` in the event of failure remediation, so that you don't act on the same allocation twice. The endpoint should be idempotent.
* Be able to reserve and clear a released allocation.
* Prevent releasing or clearing a cleared allocation 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 |
| :---- | :---- | :---- |
| `allocationId` | UUID | The BitGo ID for the allocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to allocate. |
| `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. |
| `partnersAllocationId` | string | The ID for the allocation 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: “Allocation not found” |

### Release allocation

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

Route: `PUT /bitgo/v1/allocation/:allocationId/release`

This endpoint must:

* Issue a `404` response, stating `Allocation not found`, if you have no record of the allocation or deallocation 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 allocation.
* Issue a `404` response, if BitGo calls a put on an allocation that isn’t in the reserved status on your system.
* Take an `allocationId` in the event of failure remediation, so that you don't act on the same allocation twice. The endpoint should be idempotent.
* Be able to reserve and clear a released allocation.
* Prevent releasing or clearing a cleared allocation 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 |
| :---- | :---- | :---- |
| `allocationId` | UUID | The BitGo ID for the allocation. |
| `amount` | currency: string, quantity: string | The currency type and currency amount to allocate. |
| `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. |
| `partnersAllocationId` | string | The ID for the allocation 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: “Allocation not found” |

## 1. Reserve Assets

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

```json API
POST /bitgo/v1/allocations

Request Body
{
    "allocationId": UUID
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": NonEmptyString
    "partnersAllocationId": string
    "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 following step.

```json JSON
{
    "allocationId": UUID
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": NonEmptyString
    "partnersAllocationId": string
    "partnersClientId": 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 trade their allocated assets on your platform.

```json API
PUT /bitgo/v1/allocation/{allocationId}/clear
```

Clients can now trade their allocated assets on your platform.

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

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

>Endpoint: [Update Partner Allocations](/reference/v1partnerallocationsputroute)

This step applies only to partners with **async allocations** 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 allocation asynchronously and reports the final status back to BitGo using this endpoint.

Call this endpoint after you process the allocation on your platform:

* Set `status` to `cleared` when you credit the client's account and confirm the allocation.
* Set `status` to `released` when the allocation cannot be processed and must be reversed. Include `rejectReason` when releasing.

> 📘 **Note**
>
> When you report the status back to BitGo the allocation 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/allocations \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "allocationId": "<bitgo-allocation-uuid>",
    "status": "cleared",
    "amount": {
      "currency": "ofcbtc",
      "quantity": "100000"
    },
    "clientId": "<bitgo-client-uuid>",
    "connectionId": "<bitgo-connection-uuid>",
    "partnersClientId": "<your-client-id>",
    "partnersConnectionId": "<your-connection-id>",
    "partnersAllocationId": "<your-allocation-id>",
    "nonce": "<unique-nonce>",
    "payload": "<stringified payload>",
    "signature": "<signature>"
  }'
```

To release an allocation, 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/allocations \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "allocationId": "<bitgo-allocation-uuid>",
    "status": "released",
    "rejectReason": "Unsupported currency",
    "amount": {
      "currency": "ofcbtc",
      "quantity": "100000"
    },
    "clientId": "<bitgo-client-uuid>",
    "connectionId": "<bitgo-connection-uuid>",
    "partnersClientId": "<your-client-id>",
    "partnersConnectionId": "<your-connection-id>",
    "partnersAllocationId": "<your-allocation-id>",
    "nonce": "<unique-nonce>",
    "payload": "<stringified payload>",
    "signature": "<signature>"
  }'
```

#### Step Result

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

## Next

[Create Settlements](/docs/oes-partner-settlements)