REST API›Settle (Off Exchange)›Client Allocations & Deallocations

POST

Allocate funds to partner connection

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.

Requires access token scopes: settlement_network_read, settlement_network_write

Path Params

  • connectionId string required

    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.
  • enterpriseId string required

    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.

    at least 1 characters

Body Params

object

  • 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).
    amount object
    • 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.

    at least 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.

    at least 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.

    at least 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.

    at least 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.

    at least 1 characters

Responses

200
OK

Response Body

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.
    allocation object
    • id string required
      The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
    • amount object required
      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.

      at least 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.

      at least 1 characters

    • initiatedBy string required
      The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.

      at least 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.

      at least 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 enum 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.
      false
    • evaluationId string
      The unique identifier of the policy evaluation for this allocation/deallocation. Present when policy evaluation was performed as part of the allocation flow.

      at least 1 characters

    • pendingApprovalId string
      The unique identifier of the pending approval for this allocation/deallocation. Present when policy evaluation resulted in a PENDING status requiring manual approval.

      at least 1 characters

    • policyResult string enum

      The result of the policy evaluation for this allocation/deallocation.

      • 'approved': Policy evaluation passed and the operation was allowed
      • 'rejected': Policy evaluation failed and the operation was denied Not present if no policy evaluation was performed or if evaluation is still pending.
      approvedrejected
    • status string enum 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.
      cleared
400
Bad Request
No response body
401
Unauthorized

Response Body

object

  • error string required
403
Forbidden

Response Body

object

  • error string required
404
Not Found

Response Body

object

  • error string required
422
Unprocessable Entity

Response Body

object

  • 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.
    allocation object
    • id string required
      The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
    • amount object required
      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.

      at least 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.

      at least 1 characters

    • initiatedBy string required
      The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.

      at least 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.

      at least 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 enum 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.
      false
    • evaluationId string
      The unique identifier of the policy evaluation for this allocation/deallocation. Present when policy evaluation was performed as part of the allocation flow.

      at least 1 characters

    • pendingApprovalId string
      The unique identifier of the pending approval for this allocation/deallocation. Present when policy evaluation resulted in a PENDING status requiring manual approval.

      at least 1 characters

    • policyResult string enum

      The result of the policy evaluation for this allocation/deallocation.

      • 'approved': Policy evaluation passed and the operation was allowed
      • 'rejected': Policy evaluation failed and the operation was denied Not present if no policy evaluation was performed or if evaluation is still pending.
      approvedrejected
    • status string enum 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.
      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.

      at least 1 characters

  • error string required
500
Internal Server Error

Response Body

ONE OF

  • error string required