Batch Trade and Allocations
Overview
Bakkt provides a service for clients to collectively request cryptocurrency allocations for investor accounts in bulk when necessary. Bakkt collects the allocation requests and aggregates them into a single order to submit to the market. Once filled, Bakkt processes the allocations at the average fill price of that order to the identified investor accounts.
The overall process includes opening a batch of allocations and specifying the symbol for the overall batch and batch type (notional or quantity based). Submit allocations to the batch for each investor account request while specifying the side, amount, and symbol. Specify an optional custom fee (BPS/fixed) to apply to the allocation if applicable. Close the batch and indicate the number of allocations that belong to each batch. Bakkt runs a series of validations across the requested allocations and adjusts the aggregate order size based on any allocations that fail validation. Bakkt sends the trade details for bookkeeping/investor tax reporting and sends a trading email confirmation to notify the investor of the allocation. See the following information for additional details.
Core Concepts and Functionality
Allocations
Crypto allocation involves identifying the percentage of cryptocurrency in the investor's overall investments, then choosing the blend of cryptocurrencies that match the investor's desired portfolio balances. Bakkt provides a Firm Allocation Account in order to submit batch trades for investors.
Event Notifications
Bakkt provides a durable Event Queue to connect and receive updates on cryptocurrency orders, transfers, allocations and gifting rewards. For additional information on the Event Queue, refer to the Event Notifications document. For implementation details, see the SQS section.
Notifications
Bakkt provides an end-of-day summary of investor cryptocurrency transactions. Bakkt Support helps configure notices during the Onboarding process.
Workflow
1. Creating the Firm Allocation Account
Contact Bakkt Support at [email protected] to begin submitting batch trades. Bakkt must create a Firm Allocation Account to be used by this flow
2. Submitting Batched Trade Allocation Requests and Closing Batch Trades
Use the Open Batch Trade Allocation, Request for Allocation, and Request to Close Allocation endpoints to successfully create, specify, and submit batch trade allocation requests from the Firm Allocation Account, generate an order, and process the order's associated allocations. The endpoints create and specify a batch of allocations to create an order. The required fields can be found in the open API specifications. Use the Open and Close endpoints only once per batch, but use the Allocate endpoint for each allocation request as part of the overall batch.
3. Validating Batches and Allocations
The allocation request validates all of the request data. If any data validations fail, the request receives a response with a REJECTED status and a reason text string explaining why the system rejected the request. After closing the batch, Bakkt runs a series of validations across the requested allocations and processes them accordingly. Bakkt sends message updates on the terminal states of allocations. If an allocation processes successfully, the response object contains the allocation details with a COMPLETE status; however, if the allocation fails validation, the status returns as REJECTED.
There are a variety of validations put in place when processing batch and allocation requests. See the following list for the most common errors and allocation reject reasons.
| Error and Reject Scenarios |
|---|
| Customer account does not exist |
| Firm Allocation Account does not exist |
Submitting the same clientTransactionId more than once |
| Symbol mismatches symbol of batch (when allocating to a batch) |
| Batch ID does not exist (when allocating to/retrieving from batch) |
| Allocations count mismatch (when closing batch) |
| Investor account does not have enough cryptocoin to sell |
The clientTransactionId does not exist (when retrieving allocation details) |
| Symbol does not exist |
| Allocation amount (either notional or quantity) is negative |
4. Settling Funds
Batched orders have the same markup/commission as investor trading. After processing allocations, the funds settle via Third-Party Journals (TPJs) from investor accounts.
Sample Events
Bakkt uses a Durable Event Queue for messaging. Specific notification information is located in the body of SQS messages. For additional information on the Event Queue, refer to the Event Notifications document. For implementation details, see the SQS section. See the following examples of batch events with simple payloads.
{
"event_type": "allocation/batch/1",
"message_id": "6f6ab118-5c02-41e1…",
"payload": {
"allocations": 0,
"createdAt": "2022-10-03T06:02:13.417Z",
"id": "5c394ed8-b7a3-48d8-b793-7ee6…",
"request": {
"batchTransactionId": "49136c79-3ce9-4f8d-8794...",
"symbol": "BTCUSD",
"type": "NOTIONAL"
},
"status": "OPEN"
},
"timestamp": "2022-10-03T06:02:13.424552751Z"
}
{
"event_type": "allocation/batch/1",
"message_id": "b8b55e4a-3637-42fd-80e5-e2311…",
"payload": {
"allocations": 1,
"createdAt": "2022-10-03T06:02:16.121Z",
"id": "3ac9077f-d7a6-4200-bc1f-669d567…",
"request": {
"batchTransactionId": "95875dd9-c380-4cb5… ",
"symbol": "BTCUSD",
"type": "NOTIONAL"
},
"status": "CLOSED"
},
"timestamp": "2022-10-03T06:02:16.190980550Z"
}
{
"event_type": "allocation/batch/1",
"message_id": "0c61649a-25db-424c-904e-5568b…",
"payload": {
"createdAt": "2022-06-24T14:33:31.605Z",
"id": "458b1182-6449-48e1-b2c0-3c942c…",
"netMoney": "200",
"price": "21440.92",
"quantity": "0.00932796",
"request": {
"account": "6a605008…",
"amount": "200",
"batchTransactionId": "d26q8619-7uc1-4fcf-99b6-…",
"clientTransactionId": "69d4c791-4db3-486b-b4a8-d5fb…",
"side": "BUY",
"symbol": "BTCUSD"
},
"status": "COMPLETE"
},
"timestamp": "2022-06-24T14:34:16.749988161Z"
}
{
"event_type": "allocation/batch/1",
"message_id": "6f61118-5c02-41e1…",
"payload": {
"allocations": 0,
"createdAt": "2022-10-03T06:02:13.417Z",
"id": "5c394ed8-b7a3-1118-b793-7ee6…",
"rejectReason": "Insufficient BCH available to allocate",
"request": {
"account": "AT00000",
"symbol": "BCHUSD",
"quantity": 0.0001,
"type": "QUANTITY"
},
"batchTransactionId": "49136c79-3ce9-4f8d-8794...",
"clientTransactionId": "94c28222-1111-1111-1111-a359913c4c4d",
"side": "SELL"
"status": "REJECTED"
},
"timestamp": "2022-10-03T06:02:13.424552751Z"
}
Reporting
Submitting Allocation Information for Tax Reporting
Bakkt considers all allocations as trade transactions and must post them to its bookkeeping department for cost-basis purposes noting the transaction type as Buy or Sell. Bakkt records the allocation details in its bookkeeping processes and includes this information in the investor's year-end profit/loss statement.
Updated 9 months ago