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

GET

List partner allocations and deallocations

Lists all allocations and deallocations. For use only by OES partners.

Requires access token scope: settlement_network_read

Path Params

  • enterpriseId string required

    at least 1 characters

Query Params

  • allocationIds array of strings
    Optional array of allocationIds. allocationIds are unique identifiers (UUIDs) for allocations. If UUIDs are provided, only allocations/deallocations with those UUIDs are returned. UUIDs must be submitted as a comma-separated string.
  • types array of string enums
    Optional array of types. If types are provided, only allocations/deallocations with those types are returned. Types must be submitted as a comma-separated string. allocation = records for allocations to connections. deallocation = records for deallocations from connections.
    allocationdeallocation
  • statuses array of string enums
    Optional array of statuses. If statuses are provided, only allocations/deallocations with those statuses are returned. Statuses must be submitted as a comma-separated string. cleared = records for allocations that have been cleared. released = records for allocations that have been released. reserved = records for allocations that are still reserved.
    clearedreleasedreserved
  • currencies array of strings
    Optional array of partner mapped currencies. If currencies are provided, only allocations/deallocations with those currencies are returned. Currencies must be submitted as a comma-separated string.
  • connectionIds array of strings
    Optional array of connectionIds. If connectionIds are provided, only allocations/deallocations for those connectionIds are returned. ConnectionIds must be submitted as a comma-separated string.
  • partnerIds array of strings
    Optional array of partnerIds. If partnerIds are provided, only allocations/deallocations for those partnerIds are returned. PartnerIds must be submitted as a comma-separated string.
  • clientIds array of strings
    Optional array of clientIds. If clientIds are provided, only allocations/deallocations for those clientIds are returned. ClientIds must be submitted as a comma-separated string.
  • pageNumber string integer
    The page number (integer) you wish to fetch. When provided, the API will skip pageSize * pageNumber records. Page numbers are zero-based, so the first page is 0. If not provided, defaults to 0.
  • pageSize string
    The page size (integer) you wish to fetch. When provided, the API will return at most pageSize records per page. If not provided, a default page size defined by the server will be used.
  • sortField string enum

    The field to sort results on.

    Possible values:

    • id: Sort by allocation ID.
    • updatedAt: Sort by the last updated timestamp.
    • quantity: Sort by the allocation amount quantity.

    Note: A final sort is always applied on createdAt ascending and id ascending, regardless of the specified sortField. This ensures consistent ordering for items with the same primary sort value.

    idupdatedAtquantity
  • sortDirection string enum

    The direction to sort results.

    Possible values:

    • ASC: Ascending order (lowest to highest, A to Z, oldest to newest)
    • DESC: Descending order (highest to lowest, Z to A, newest to oldest)

    If not specified, defaults to ASC (ascending).

    ASCDESC

Responses

200
OK

Response Body

object

  • allocations array of objects required
    allocations 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.

      ONE OF

      • currency string required

        at least 1 characters

      • quantity string required
    • 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 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.
    • 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
    • reason string nullable 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

    • 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.
      clearedreleasedreserved
    • type string enum required

      The type of the entity.

      Possible values:

      • allocation: Represents an allocation of funds to a connection. This moves funds from a client's BitGo account to make them available for the specified connection.
      • deallocation: Represents a deallocation of funds from a connection. This moves funds from a connection back to the client's BitGo account.
      allocationdeallocation
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
500
Internal Server Error

Response Body

object

  • error string required