How to Journal Cash or Securities from One Client Account to Another by Broker API

21 Apr 2021

How to Journal Cash or Securities from One Client Account to Another by Broker API

This tutorial is a step-by-step demonstration of how to journal cash or securities from one client account to another via the Broker API and is part of the Alpaca 101 Tutorial Series. We will move forward assuming that you’ve registered on the Alpaca website. If you haven’t please visit Alpaca and sign up. Feel free to check out the other tutorials in this series at Alpaca Resources.

Please note that this tutorial reflects a sandbox testing environment. If you decide to transition to a live production environment, features and entitlements may differ to ensure handling of clients’ live accounts are compliant with all applicable rules and regulations.

What is Broker API?

Alpaca is built for developers and traders. That being said we are incredibly excited to announce we have established our very own broker product that can evolve alongside the Alpaca platform. Alpaca users can develop in sandbox environments, allowing users to access all the functionality of an operational brokerage in parallel with becoming compliant with applicable rules and regulations should you decide to transition to a live production environment. We are releasing a series of tutorials to provide guidance on the core features of the Broker API, so make sure to check out Alpaca Resources. Let’s get started!

How to Journal Events

Step 1: Broker Dashboard

Similar to the Algo Dashboard, the Broker Dashboard displays all of the information relevant to one’s broker account. The main page, shown below, includes an overview of the number of active accounts, assets under management (AUM) along recent signups, transactions, and orders. When logging in for the first time, you will notice there is not any information present in the dashboard as below

There are also subpages for the firm’s balance, active accounts, transactions (orders and ACH/Wire transfers), and documents.

Step 2: Live Testing

To set up your environment first navigate to the API/Devs page where there is a box in the right-hand corner called Seed Env. By clicking this, your environment will be populated with random test users. This allows you to start testing different API calls without needing to create user accounts in your environment. After this, your dashboard should contain randomly generated test signups and amounts under Assets Under Management (AUM).

Now that the sandbox environment contains users, we can move on to testing out the API calls. Navigate first to the API/Devs page and then the Live Testing page which will look like this

This will be the medium in which we test the API call in the next section.

Step 3: Sending the Request Body

Let’s create a raw request to journal cash, from one client’s account to another. In this tutorial, we will be journaling $51 of cash (in USD) from one account to the other. As we wish to create a Journal entry we POST the following sample request to the endpoint /v1/journals.v2 . Note that the entry_type specifies the type of journal; if one wants to journal cash between accounts they would pass in the string JNLC while if one wants to journal securities between accounts they would pass JNLS.

Find the JSON body for our request below

{
       "from_account": "c94bu7rn-4483-4199-840f-6c5fe0b7ca24",
       "entry_type": "JNLC",
       "to_account": "fn68sbrk-6f2a-433c-8c33-17b66b8941fa",
       "amount": "51"
}

Sample Request Object

Step 4: Response for a Successful Request

If all has been successful one will receive the following response object with attributes specific to the entry_type of the request. As we sent a request to journal cash between two accounts (equivalently entry_type: JNLC) our response is a JNLC object which is shown below. Let’s note some of the attributes in the response are the same as in our request such as from_account to_account entry_type amount. However, we see there are additional attributes in our response notably, id status and settle_date which represent the journal id, status of the journal, and date of settlement respectively.

{
  "id": "f45g67h8-d1fc-4136-aa4f-cf4460aecdfc",
  "to_account": "g7h7rg66-6f2a-433c-8c33-17b66b8941fa",
  "entry_type": "JNLC",
  "amount": "51",
  "status": "executed",
  "from_account": "8k4f3d-4483-4199-840f-6c5fe0b7ca24",
  "settle_date": "2020-12-24"
}

For more information please see our Broker Documentation.

Great! Now, moving forward here are some important points to remember:

Depending on whether you are looking to journal cash or securities between client accounts, the expected response object will be respectively either a JNLC or a JNLS object with different attributes
While we referred to client accounts in this tutorial a client account can also be your firm account too, which allows for features such as a cash reward program.
We only discussed creating a journal through the endpoint POST /v1/journals.v2 however some other important endpoints in the Journals API include GET /v1/journals.v2 to retrieve a journal and DELETE /v1/journals.v2/{journal_id} to delete a pending journal

Thank you for using Alpaca. Here are a couple more links that you might be interested in.

Alpaca GitHub repository

Alpaca Blog

Alpaca Forum

Alpaca API documentation

Sign up for the weekly newsletter to keep up with the API updates and upcoming competitions, job opportunities by clicking here.

You can also follow Alpaca and our weekly updates on our LinkedIn, Alpaca Community Slack, and @AlpacaHQ on Twitter!

Commission-Free trading means that there are no commission charges for Alpaca self-directed individual cash brokerage accounts that trade U.S. listed securities through an API. Relevant SEC and FINRA fees may apply.

Brokerage services are provided by Alpaca Securities LLC ("Alpaca"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.