DocumentationImplementation Docs
API StatusLogin

Omnibus

Suggest Edits

Overview

This quickstart describes how to get up and running with DriveWealth's REST API. The following sections provide a hello world example demonstrating how to make a stock purchase within an omnibus account:

  • Generate an Authentication Token.
  • Fund the account
  • Make a Trade


Prerequisites

Before you begin, ensure you have your DriveWealth client app key (dw-client-app-key).

Idempotency-Key Header
Many of DriveWealth's APIs can take in an optional Idempotency-Key header. An Idempotency-Key is a unique ID that you create (e.g. using a GUID generation tool) to uniquely identify a request.

Should the request fail or be interrupted, you can retry the request with the same Idempotency-Key header value for up to four days.

Requests should never be unconditionally retried, as failing to receive a response does not necessarily mean that DriveWealth is not receiving and responding. We recommend an exponential backoff or similar pattern of retries, before switching to failover procedures, such as:

Issue request at time T.

Retry 1: T + 1 second
Retry 2: T + 3 seconds
Retry 3: T + 10 seconds
Retry 4: T + 30 seconds

For more information see Idempotent Requests.



Generate an Authentication Token

An authentication token is required for your client app to make requests with our API on behalf of the end user. Once generated, this token must be included when invoking each subsequent DriveWealth REST endpoint in your app.



Auth Request

Follow the steps below to generate an authentication token:

  • (Optional) Generate or create a unique Idempotency-Key value.
  • Invoke POST /back-office/auth and pass in the following:
    • For the header:
      • Idempotency key as the Idempotency-Key (optional)
      • Client app ID as the dw-client-app-key
    • For the body:
      • User's name as the username field
      • User’s password as the password field
      • Set appTypeID to 4.
curl --request POST \
     --url https://bo-api.drivewealth.io/back-office/auth/tokens \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'dw-client-app-key: 69204e73-561d-4...' \
     --data '{"clientID": "0oa5rc70..","clientSecret": "fr2k5wntp..."}'


Auth Response

The authToken field in the response contains the generated authentication token:

{
    "token_type": "Bearer",
    "expires_in": "3600",
    "access_token": "eyJraWQiOiJjY1lyLVRDUTZBR0w5OWl3TTFyMjAwWlNSdnI0dVBCZ3QxZU42eDhyRVVrIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULmkwRmJtbzJkdU5Ya3EzREtyU3NkVTN4M3V3MnljSjhTdkctel9hMFM0VWMiLCJpc3MiOiJodHRwczovL2FwMS1kcml2ZXdlYWx0aC5va3RhcHJldmlldy5jb20vb2F1dGgyL2F1czJ6bWJsNnBOcE4zelZEMWQ3IiwiYXVkIjoiRFdBdXRoU2VydmVyREVWIiwiaWF0IjoxNjY0OTA4OTA2LCJleHAiOjE2NjQ5MTI1MDYsImNpZCI6IjBvYTVubnk0bzlCZU1zQVlRMWQ3Iiwic2NwIjpbImFsbF90cmFkZXIiXSwic3ViIjoiMG9hNW5ueTRvOUJlTXNBWVExZDciLCJwcm9maWxlIjp7InBlcm1pc3Npb25JRCI6IjY5NTQ3OWFhLTVmN2ItNDRhOC1hMTE4LWFhOWU2N2M3YmUyZSIsInJvbGUiOiJBTExfVFJBREVSIiwicGFydG5lcklEIjoiMThkNTk3NjctNzNiOC00YTM0LWE1NDItMWNjZDIyYmEzNjAyIiwidXNlcklEIjoiNzA1YzFiMDMtM2Y2YS00MmFhLTgwN2EtMWY0NGMwNjc0ZDhmIn19.p3fspVtifQ_Gr4K3pi5fTorCBrcuVkRxk-yNLANgiKvl3t0BKraMT7_Y8c8opsKmNUwLS2K3YlBA0vrskzxeacWtEDx_JGtz_zKS_GXWTPDNNd77Zy0P6vfNfDjc_Hbzpp90dAICrTwvrcihNbyLeL3Zq7LisGpDkYtdxwB73AHtU6qIQvPY-iYaWBLfJ9IZrTTNWd5Qqy8ICJNunrS5riD2O3o4idyzMoUnFimUAoiAwgqtSOh4Loe57kPQsCgNRoba0zbnXKNd0eyMHCCdM0BXW_uhyJIfdGUXVzCcg9k_G80sWnefTeitwdX0S657vKHTjyLsGJSc06ZggGdlag",
    "scope": "all_trader"
}

You will use the generated authToken in the sections below to make requests on behalf of the user in your client app.

🚧

Note: Funding is not specific to omnibus accounts. Your exact funding method may be different from this quickstart guide.

Fund the Account**

For this quickstart, use POST /back-office/funding/deposits to instantly fund the user's DriveWealth brokerage account:

Funding Request

Invoke POST /back-office/funding/deposits and pass in the following:

For the headers:

  • Authentication token

  • Idempotency key (optional)

  • Client app ID

For the body:

  • accountNo of the omnibus DriveWealth brokerage account

  • Funding details including amount, currency, and type

curl --location --request POST 'https://bo-api.drivewealth.io/back-office/funding/deposits' \
--header 'Authorization: Bearer :authToken' \
--header 'dw-client-app-key: f988...' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "accountNo": "ZBG...",
  "amount": 500,
  "currency": "USD",  
  "type": "INSTANT_FUNDING", 
  "note": "Some money for funding" 
}'


Funding Response

The id field in the response identifies the funding request:

{
    "id": "ZBCB000...",
    "accountNo": "ZBC...",
    "category": "DEPOSIT",
    "currency": "USD",
    "amount": 500,
    "status": {
        "id": 1,
        "message": "Pending",
        "updated": "2022-04-26T17:56:25.295Z"
    },
    "source": {
        "id": "INSTANT_FUNDING",
        "brand": "Instant funding",
        "meta_info": "Some money for funding"
    },
    "created": "2022-04-26T17:56:25.295Z",
    "accountID": "261fb...",
    "userID": "261fb...",
    "transactionCode": "JOURNAL",
    "wlpFinTranTypeID": "f197...",
    "batch": true,
    "account_number": "ZBG..."
}


Make a Trade

Everything is now set up and your client app can now make a trade on behalf of the user. The following subsections show how to:

  • Purchase a Stock
  • Verify the Trade Order
  • The POST /back-office/orders endpoint is used to buy and sell stocks.


Trade Request

Invoke POST /back-office/orders and pass in the following:

  • Values generated from Create a DriveWealth Brokerage Account:
    • The user's linked bank account number in the bankAccountNumber body field.
    • DriveWealth account number in the accountNo body field.
    • The remaining body fields to specify the order details.
curl --location --request POST 'https://bo-api.drivewealth.io/back-office/orders' \
--header 'Authorization: Bearer :authToken' \
--header 'dw-client-app-key: f988...' \
--header 'Idempotency-Key: 175bf...' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "bankAccountNumber":"12345",
  "accountNo":"yyy",
  "orderType":"MARKET",
  "symbol":"VTI",
  "side":"BUY",
  "quantity":"10"
}'


Trade Response

The orderID field uniquely identifies the order and can be used in subsequent requests (e.g. to Verify the Trade Order). The orderNo field is a user-friendly order identifier that you can display to the user:

{
  "orderID": "EF.418a55...",
  "orderNo": "EFXM000103"
}


Verify Trade Request

Invoke GET /back-office/orders/{order-id} to check the status of stock purchase.

Pass the orderID generated in the previous section in the {order-id} path parameter:

curl --location --request GET 'https://bo-api.drivewealth.io/back-office/orders/EF.418a55...' \
--header 'Authorization: Bearer :authToken' \
--header 'dw-client-app-key: f988...' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'


Verify Trade Response

The status field in the response provides the current state of the order. In this example the value is FILLED, indicating that the stock has been successfully purchased:

{
  "id": "GB.703...",
  "orderNo": "EFXM000103",
  "type": "MARKET",
  "side": "BUY",
  "status": "FILLED",
  "symbol": "VTI",
  "averagePrice": 16.07,
  "totalOrderAmount": 10,
  "cumulativeQuantity": 0.92304,
  "quantity": 0.92304,
  "amountCash": 1500,
  "fees": 0.01,
  "createdBy": "cc07f9...",
  "userID": "3bfdb8...",
  "accountID": "cc07f91...",
  "accountNo": "DWRW000001",
  "created": "2019-02-14T18:56:07.411Z"

Updated 8 months ago