Placing Digital Assets Orders

API Reference:

Overview

To create a buy or sell order, DriveDigital requires the customer Crypto accountID , symbol & side (unless using RFQ), ipAddress, quantity (whole share) or amountCash, and [order type] must be set to MARKET.

Important data to display to a customer

Order Types

  1. For RFQ orders - prior to submitting a trade, the total order amount will be displayed to the customer.
  2. For "immediate execute" orders - prior to submitting a trade, the estimated total order amount will be displayed to the customer. This is calculated by the partner, usually on the front end. The final price will not match exactly to the estimate price but will be close to it. The actual amount of cash paid or received depends on the final execution amount.
  3. After submitting a trade, the final total order amount is provided through the order status API and in other places.

Order status and cumulative quantity

Customers should always be able to view the current status of the order they have placed. Partners can opt to integrate with either the Events or Order Status API to get information on order execution and status. DriveDigital recommends utilizing the events API, such that polling individual order statuses is not needed.

  • Events API: to receive an SQS-based notification when an order is created, updated, and completed
  • Order Status API: to poll for current and updated status

There are 3 statuses that DriveDigital considers immutable: FILLED | REJECTED | PENDING.

When an order is submitted, it will be returned with a status of PENDING. From here the status can be updated to FILLED or REJECTED. Orders can only be filled or rejected in their entirety. In cases where orders are REJECTED, the statusMessage should be referenced for the rationale

There are 3 order status definitions:

  1. FILLED – The customer’s order has been 100% executed
  2. REJECTED – The order is rejected after placement
  3. PENDING – Orders will enter the "PENDING" state very temporarily and transition to FILLED or REJECTED promptly.

Order Error Messages

In the event a customer’s order is rejected, an error code, status, and description of the rejection will be returned to the customer. You can find all common order error messages here. Ensure that the details of a rejection is given to the customer to limit confusion.

There are several reasons why an order may be REJECTED. If a Partner runs out of prefunding and an end user wishes to make a purchase, a 422 error will appear with a message saying "insufficient funds". This is not a user error, but it is important to maintain some level of tracking for instances where 422 errors appear. When the "prefunded" amount is depleted, only SELLS will be permitted.

How it works

Since trades are effectively settled instantly, the Partner can leverage the reconciliation endpoint to retrieve the status of executed trades on a rolling 15 minute basis. In conjunction with the reconciliation endpoint, the Partner can also query the balance of the house account and the DriveDigital "residual" account (both updated every 15 minutes) to manage the pre-fund balance.

Note: Partners are free to pre-fund above the maintenance levels if desired. The larger the pre-fund balance, the smaller the likelihood of trading interruptions.

Example - fully funded workflow w/15min reconciliation cycle:
T+0 09:00: $100 deposit received from Partner

  • houseAccount: $100
  • residualAccount: $0
  • customerAccount:
    -cashBalance: $0
    -btcBalance: 0
  • reconciliationReport1:
    -status: PROCESSING
    -amount: $0

T+0 09:05: Customer purchases $30 BTC

  • houseAccount: $100
  • residualAccount: $0
  • customerAccount:
    -cashBalance: -$30
    -btcBalance: 0.001
  • reconciliationReport1:
    -status: PROCESSING
    -amount: -$30

T+0 09:15: Reconciliation endpoint status updated to SUCCESSFUL, next Reconciliation report created

  • houseAccount: $70
  • residualAccount: $0
  • customerAccount:
    -cashBalance: $0
    -btcBalance: 0.001
  • reconciliationReport1:
    -status: SUCCESSFUL
    -amount: -$30
  • reconciliationReport2:
    -status: PROCESSING
    -amount: $0

Example - under funded workflow w/15min reconciliation cycle:
T+0 09:00: $100 deposit received from Partner

  • houseAccount: $100
  • residualAccount: $0
  • customerAccount:
    -cashBalance: $0
    -btcBalance: 0
  • reconciliationReport1:
    -status: PROCESSING
    -amount: $0

T+0 09:05: Customer purchases $150 BTC

  • houseAccount: $100
  • residualAccount: $0
  • customerAccount:
    -cashBalance: -$150
    -btcBalance: 0.005
  • reconciliationReport1:
    -status: PROCESSING
    -amount: -$150

T+0 09:15: Reconciliation endpoint status updated to SUCCESSFUL, next Reconciliation report created

  • houseAccount: $0
  • residualAccount: -$50
  • customerAccount:
    -cashBalance: $0
    -btcBalance: 0.005
  • reconciliationReport1:
    -status: SUCCESSFUL
    -amount: -$150
  • reconciliationReport2:
    -status: PROCESSING
    -amount: $0

T+0 09:25: $200 deposit received from Partner

  • houseAccount: $150
  • residualAccount: $0
  • customerAccount:
    -cashBalance: $0
    -btcBalance: 0.005
  • reconciliationReport1:
    -status: SUCCESSFUL
    -amount: -$150
  • reconciliationReport2:
    -status: PROCESSING
    -amount: $0