Allocate Assets

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 is rejected, 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 - Ensure your access token has the following permissions:
  • Settlement Network - Read
  • Settlement Network - Write
• Generate Signature
• Activate Client Connections

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 funds should be reserved.
• Respond with a 200, idempotently, if the allocation is already cleared. No additional funds 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 the allocation was rejected prior.
  • Return the previously approved state, if the allocation 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 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.
• Include the deallocationId and allocationId as part of a one unified and unique index.
• 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 a cleared allocation 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 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.
• Include the deallocationId and allocationId as part of a one unified and unique index.
• 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 a cleared allocation 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 allocation:

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
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
    "partnerAllocationId": string
    "partnerClientId": 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.

Copy code block
1
2
3
4
5
6
7
8
9
10
{
    "allocationId": UUID
    // Amount in base units. For example, satoshis.
    "amount": { currency: string, quantity: number }
    "clientId": UUID
    "connectionId": UUID
    "partnersConnectionId": NonEmptyString
    "partnerAllocationId": string
    "partnerClientId": 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.

Copy code block
1
PUT /bitgo/v1/allocation/{allocationId}/clear

Clients can now trade their allocated assets on your platform.

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

Next

Create Settlements