## 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

<br>

<br>

### 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. ](πŸ”—ο»Ώ)ο»Ώ

<br>

<br>

### 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.

<br>

<br>

### 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.

ο»Ώ

<br>

<br>

### Auth Response

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

ο»Ώ

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

ο»Ώ

<br>

<br>

### Funding Response

The id field in the response identifies the funding request:

ο»Ώ

<br>

<br>

### 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.

<br>

<br>

### 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.

ο»Ώ

<br>

<br>

### 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:

ο»Ώ

<br>

<br>

### 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:

ο»Ώ

<br>

<br>

### 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:

ο»Ώ