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, 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
• Activate Client Connections

Steps

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
}

Step Result

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

Step Result

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