Allocate funds to partner connection

post/api/network/v1/enterprises/{enterpriseId}/clients/connections/{connectionId}/allocations

This API call allows clients to allocate funds to a connected partner for trade. A successful allocation indicates that funds are locked at BitGo and available for spend on the connected partner. Note: Allocations will happen synchronously and allocated amounts can be viewed in the BitGo application or via a balances endpoint.

Path Parameters

  • connectionIdstringRequired
    The unique identifier of the connection you want to allocate funds to. This connection: - Must be a valid, established connection between your enterprise and a partner. - Determines where the allocated funds will be available for use. - Should be pre-established before attempting to allocate funds.
  • enterpriseIdstringRequired
    The unique identifier of your enterprise. This identifier: - Represents your organization within the BitGo system. - Is used to validate you have permission to perform this action. - Must match the enterprise associated with your API credentials.
    Min length: >= 1 characters

Request Body

amount object required
The amount to allocate in base units. Contains both the currency identifier and the quantity in the currency's base units. The exact base units depend on the currency (e.g., satoshis for BTC, wei for ETH).
currency string required
quantity string required
clientExternalId string required
A unique external identifier for the allocation. This identifier: - Must be unique for each distinct allocation request. - Is used for idempotence to prevent duplicate allocations. - Allows clients to correlate allocations with their own systems. - Should be stored by the client for tracking and reconciliation.
Min length: >= 1 characters
nonce string required
Unique nonce to prevent replay attacks. This value: - Must be unique for each request requiring a nonce. - Should be a cryptographically strong random value. - Is used as part of the request signing process. - Helps ensure the signature can only be used once.
Min length: >= 1 characters
notes string
Optional notes to attach to the allocation. These notes: - Can provide additional context about the purpose of the allocation. - Are stored with the allocation record. - May be useful for auditing, record-keeping, or operational purposes. - Are visible to both client and partner.
Min length: >= 1 characters
payload string required
Payload formed by stringifying the object containing all other request properties. This includes: - amount: The amount to allocate. - clientExternalId: Your unique identifier for this allocation. - nonce: A unique value to prevent replay attacks. - notes: Optional notes about the allocation. - connectionId: The connection to allocate funds to. - enterpriseId: Your enterprise ID. The payload must be signed using your BitGo account's private key to create the signature parameter.
Min length: >= 1 characters
signature string required
Digital signature of the payload parameter. This signature: - Must be created using your BitGo account's private key. - Verifies that the request is authentic and hasn't been tampered with. - Provides non-repudiation for the allocation request.
Min length: >= 1 characters

200 Response

One of
allocation object required
The allocation record in its cleared state. This contains all allocation details with a status of 'cleared', indicating the allocation was successfully completed.
id string required
The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
amountOne ofrequired
The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.
connectionId string required
The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
clientExternalId string required
External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.
Min length: >= 1 characters
partnerExternalId string
External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.
Min length: >= 1 characters
initiatedBy string required
The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
Min length: >= 1 characters
notes string
Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.
Min length: >= 1 characters
createdAt string <date-time>required
The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
updatedAt string <date-time>required
The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
retriable boolean required
Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
Allowed value: false
status string required
Status of the allocation/deallocation. Possible values: - reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution. - cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation. - released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
Allowed value: cleared

400 Response

401 Response

error string required

403 Response

error string required

404 Response

error string required

422 Response

allocation object required
The allocation record in its released state. This contains all allocation details with a status of 'released', indicating the allocation was not completed and funds were returned. The reason field will explain why the allocation was released.
id string required
The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
amountOne ofrequired
The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.
connectionId string required
The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
clientExternalId string required
External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.
Min length: >= 1 characters
partnerExternalId string
External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.
Min length: >= 1 characters
initiatedBy string required
The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
Min length: >= 1 characters
notes string
Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.
Min length: >= 1 characters
createdAt string <date-time>required
The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
updatedAt string <date-time>required
The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
retriable boolean required
Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
Allowed value: false
status string required
Status of the allocation/deallocation. Possible values: - reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution. - cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation. - released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
Allowed value: released
reason string required
The reason that the allocation/deallocation is not cleared. Provides a descriptive explanation for why the allocation is in the reserved state. Will not be defined if the allocation is cleared.
Min length: >= 1 characters
error string required

500 Response

One of
error string required