Journals #

Journals API allows you to move cash or securities from one account to another.

There are two types of journals:

JNLC #

Journal cash between accounts. You can simulate instant funding in both sandbox and production by journaling funds between your pre-funded sweep accounts and a user’s account.

You can only journal cash from a firm account to a user account and vice-versa but not customer to customer.

JNLS #

Journal securities between accounts. Reward your users upon signing up or referring others by journaling small quantities of shares into their portfolios.

You can only journal securities from a firm account to a user account and not vice-versa or customer to customer.

For more on Journals click here

The Journal Object #

Sample JNLC Object # 

{
  "id": "h7h5g33f-ef01-4458-9a4b-9598727a406f",
  "to_account": "3gtt65jd-6f2a-433c-8c33-17b66b8941fa",
  "entry_type": "JNLC",
  "status": "executed",
  "from_account": "8fjkjn-4483-4199-840f-6c5fe0b7ca24",
  "settle_date": "2020-12-24",
  "system_date": "2020-12-24",
  "net_amount": "115.5",
  "description": "this is a test journal",
  "currency": "USD"
}

Sample JNLS Object # 

{
  "id": "f45g67h8-d1fc-4136-aa4f-cf4460aecdfc",
  "to_account": "g7h7rg66-6f2a-433c-8c33-17b66b8941fa",
  "entry_type": "JNLS",
  "symbol": "AAPL",
  "qty": "0.5",
  "price": "128.23",
  "status": "executed",
  "from_account": "8k4f3d-4483-4199-840f-6c5fe0b7ca24",
  "settle_date": "2020-12-24",
  "system_date": "2020-12-24",
  "description": "this is a test journal"
}

Attributes #

Attribute Type Notes
id string/UUID The journal ID
to_account string The account ID that received the journal - account_status must equal to ACTIVE
from_account string The account ID that initiates the journal - account_status must equal to ACTIVE or CLOSED
entry_type string ENUM: JNLC or JNLS
symbol string In the case of JNLS - the symbol of the security journaled
qty string In the case of JNLS - the quantity of the securities journaled
price string In the case of JNLS - the price of the security journaled
currency string Currency denomination of the journal. USD by default.
status ENUM.JournalStatus The status of the journal
settle_date date Date string in “%Y-%m-%d” format
system_date date Date string in “%Y-%m-%d” format
net_amount string In the case of JNLC - the total cash amount journaled
description string

ENUM.JournalStatus #

Status Description
queued Journal in queue to be processed. Journal is not processed yet.
sent_to_clearing Journal sent to be processed by Alpaca’s booking system. The journal is not processed yet.
pending Journal pending to be processed as it requires manual approval from Alpaca operations (for example due to hitting JNLC daily limits).
executed Journal executed and balances updated for both sides of the journal transaction. This is not a final status, journals can be reversed if there is an error.
rejected Journal rejected. Please try again.
canceled Journal canceled. This is a FINAL status.
refused Journal refused. Please try again.
deleted Journal deleted. This is a FINAL status.
correct Journal is corrected. Previously executed journal is cancelled and a new journal is corrected amount is created. This is a FINAL status.

Transitions:

  • On creation the journal will be created in queued state.
  • queued -> sent_to_clearing transition shows that the request has been submitted into our booking.
  • In case the journal hit any limits that require manual approvals it will be put into pending state. Alpaca team will review the journal and approve it after the inspection.
  • Otherwise, if the journal doesn’t need manual approval, the journal will go into one of the other statuses (rejected, canceled, deleted, executed).

Fixtures #

Journals API supports fixtures in Sandbox Environment. You can pass the desired status in the description field when creating a JNLC or JNLS.

Status Description
rejected will be rejected EOD
pending will be pending forever.

The default maximum amount for journals is $50. Use only ENUM: pending or rejected. Journal’s status will become this value at the end of the current market day (will default to executed if no fixture is inputted).

No Fixtures #

  • anything below limit is executed immediately
  • anything above limit is pending until executed at EOD,

Creating a Journal #

POST /v1/journals

Request #

Sample Request # 

{
  "from_account": "c94bu7rn-4483-4199-840f-6c5fe0b7ca24",
  "entry_type": "JNLC",
  "to_account": "fn68sbrk-6f2a-433c-8c33-17b66b8941fa",
  "amount": "51",
  "description": "test text /fixtures/status=rejected/fixtures/"
}

Parameters #

Attribute Type Requirement Notes
to_account string
Required
The account_id you wish to journal to
from_account string
Required
The account_id you wish to journal from
entry_type string
Required
ENUM: JNLC or JNLS
amount string/numeric
Required
Required if entry_type = JNLC
symbol string
Required
Required if entry_type = JNLS
qty string/numeric
Required
Required if entry_type = JNLS. The value should have 9 or fewer decimal places.
currency string
Optional
Currency of the journal request. Required if account is non-USD under LCT.
description string
Optional
Max 1024 characters. Can include fixtures for amounts that are above the transaction limit
transmitter_name string
Optional
Max 255 characters. See more details about Travel Rule.
transmitter_account_number string
Optional
Max 255 characters. See more details about Travel Rule.
transmitter_address string
Optional
Max 255 characters. See more details about Travel Rule.
transmitter_financial_institution string
Optional
Max 255 characters. See more details about Travel Rule.
transmitter_timestamp string
Optional
RFC 3339 format. See more details about Travel Rule.

Fixture Rules

  • No Fixtures
    • anything below limit is executed immediately
    • anything above limit is pending until executed at EOD,
  • With Fixtures
    • any status = rejected will be rejected EOD
    • any status = pending will be pending forever

Response #

A Journal object

Error Codes #

400 - Invalid Request Body
404 - Account Not Found
403 - Insufficient Balance (JNLC) or Insufficient Assets (JNLS)

Creating a Batch Journal Transaction (One-to-Many) #

You can also create a batch journal request by using the following endpoint. This is enabled on JNLC for now only.

POST /v1/journals/batch

Request #

Sample Request # 

{
  "entry_type": "JNLC",
  "from_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
  "entries": [
    {
      "to_account": "d7017fd9-60dd-425b-a09a-63ff59368b62",
      "amount": "10"
    },
    {
      "to_account": "94fa473d-9a92-40cd-908c-25da9fba1e65",
      "amount": "100"
    },
    {
      "to_account": "399f85f1-cbbd-4eaa-a934-70027fb5c1de",
      "amount": "1000"
    }
  ]
}

Attributes #

Attribute Type Requirement Notes
entry_type string
Required
ENUM: JNLC or JNLS
from_account string
Required
The originator of funds. Most likely is your Sweep Firm Account
to_account string
Required
The ID of the to_account that you want to journal into
amount string/number
Required
Journal amount in USD
description string
Optional
Journal description, gets returned in the response

Response #

Every single request must be valid for the entire batch operation to succeed.

In the case of a successful request, the response will contain an array of journal objects with an extra attribute error_message in the case when a specific account fails to receive a journal.

Sample Response # 

[
  {
    "error_message": "",
    "id": "0a9152c4-d232-4b00-9102-5fa19aca40cb",
    "entry_type": "JNLC",
    "from_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
    "to_account": "d7017fd9-60dd-425b-a09a-63ff59368b62",
    "symbol": "",
    "qty": null,
    "price": null,
    "status": "pending",
    "settle_date": null,
    "system_date": null,
    "net_amount": "10",
    "description": ""
  },
  {
    "error_message": "",
    "id": "84379534-bcee-4c22-abe8-a4a6286dd100",
    "entry_type": "JNLC",
    "from_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
    "to_account": "94fa473d-9a92-40cd-908c-25da9fba1e65",
    "symbol": "",
    "qty": null,
    "price": null,
    "status": "pending",
    "settle_date": null,
    "system_date": null,
    "net_amount": "100",
    "description": ""
  },
  {
    "error_message": "",
    "id": "56f106e5-25a4-4eee-96fa-25bb05dc86bc",
    "entry_type": "JNLC",
    "from_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
    "to_account": "399f85f1-cbbd-4eaa-a934-70027fb5c1de",
    "symbol": "",
    "qty": null,
    "price": null,
    "status": "pending",
    "settle_date": null,
    "system_date": null,
    "net_amount": "1000",
    "description": ""
  }
]

Attributes #

Attribute Type Notes
error_message string Description of why this journal transaction failed
id string/UUID The journal ID
entry_type string ENUM: JNLC or JNLS
from_account string The account ID that initiated the journal
to_account string The account ID that received the journal
symbol string In the case of JNLS - the symbol of the security journaled
qty string In the case of JNLS - the quantity of the securities journaled
price string In the case of JNLS - the price of the security journaled
status ENUM.JournalStatus The status of the journal
settle_date date Date string in “%Y-%m-%d” format
system_date date Date string in “%Y-%m-%d” format
net_amount string In the case of JNLC - the total cash amount journaled
description string Journal description passed in the request

Error Codes #

Note that if there is an invalid account_id the whole batch operation will be canceled.

400 - Invalid Request Body
404 - Account Not Found
403 - Insufficient Balance (JNLC) or Insufficient Assets (JNLS)

Creating a Reverse Batch Journal Transaction (Many-to-One) #

You can also create a batch journal request by using the following endpoint. This is enabled on JNLC for now only.

POST /v1/journals/reverse_batch

Request #

Sample Request # 

{
  "entry_type": "JNLC",
  "to_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
  "entries": [
    { "from_account": "8e00606a-c9ac-409a-ba45-f55e8f77984a", "amount": "10" },
    { "from_account": "b9b19618-22dd-4e80-8432-fc9e1ba0b27d", "amount": "100" },
    { "from_account": "c96a5e16-7fca-425a-b67b-0814d064bfc0", "amount": "100" }
  ]
}

Attributes #

Attribute Type Requirement Notes
entry_type string
Required
ENUM: JNLC or JNLS
to_account string
Required
The destination of funds. Most likely is your Sweep Firm Account
from_account string
Required
The ID of the from_account that you want to journal from
amount string/number
Required
Journal amount in USD
description string
Optional
Journal description, gets returned in the response

Response #

Every single request must be valid for the entire batch operation to succeed.

In the case of a successful request, the response will contain an array of journal objects with an extra attribute error_message in the case when a specific account fails to submit a journal.

Sample Response # 

[
  {
    "error_message": "",
    "id": "6a6cfd09-21cb-4d7c-a656-268b93417491",
    "entry_type": "JNLC",
    "from_account": "8e00606a-c9ac-409a-ba45-f55e8f77984a",
    "to_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
    "symbol": "",
    "qty": null,
    "price": "0",
    "status": "queued",
    "settle_date": null,
    "system_date": null,
    "net_amount": "10",
    "description": ""
  },
  {
    "error_message": "",
    "id": "dbf11812-8d4c-47e0-a460-1a1993fffce3",
    "entry_type": "JNLC",
    "from_account": "b9b19618-22dd-4e80-8432-fc9e1ba0b27d",
    "to_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
    "symbol": "",
    "qty": null,
    "price": "0",
    "status": "queued",
    "settle_date": null,
    "system_date": null,
    "net_amount": "100",
    "description": ""
  },
  {
    "error_message": "",
    "id": "1f59b00b-dac9-4f67-80d7-dc1f6b0e214a",
    "entry_type": "JNLC",
    "from_account": "c96a5e16-7fca-425a-b67b-0814d064bfc0",
    "to_account": "8f8c8cee-2591-4f83-be12-82c659b5e748",
    "symbol": "",
    "qty": null,
    "price": "0",
    "status": "queued",
    "settle_date": null,
    "system_date": null,
    "net_amount": "100",
    "description": ""
  }
]

Attributes #

Attribute Type Notes
error_message string Description of why this journal transaction failed
id string/UUID The journal ID
entry_type string ENUM: JNLC or JNLS
from_account string The originator account ID
to_account string The destination account ID
symbol string In the case of JNLS - the symbol of the security journaled
qty string In the case of JNLS - the quantity of the securities journaled
price string In the case of JNLS - the price of the security journaled
status ENUM.JournalStatus The status of the journal
settle_date date Date string in “%Y-%m-%d” format
system_date date Date string in “%Y-%m-%d” format
net_amount string In the case of JNLC - the total cash amount journaled
description string Journal description passed in the request

Error Codes #

Note that if there is an invalid account_id the whole batch operation will be canceled.

400 - Invalid Request Body
404 - Account Not Found
403 - Insufficient Balance (JNLC) or Insufficient Assets (JNLS)

Retrieving Journal Entries #

GET/v1/journals

Request #

Parameters #

Attribute Type Requirement Notes
after string
Optional
By journal creation date. Format: 2020-01-01
before string
Optional
By journal creation date. Format: 2020-01-01
status string
Optional
ENUM.JournalStatus
entry_type string
Optional
ENUM: JNLC or JNLS
to_account string
Optional
The account that received the journal
from_account string
Optional
The account that initiated the journal

Response #

An array of journal objects.

Error Codes #

401 - Invalid Params

Retrieving a Single Journal Entry #

GET /v1/journals/{journal_id}

You can query a specific journal entry that you submitted to Alpaca by passing into the query the journal_id.

Request #

N/A

Response #

Will return a journal entry if a journal entry with journal_id exists, otherwise will throw an error.

Deleting a Journal #

DELETE /v1/journals/{journal_id}

You can only delete a journal if the journal is still in a pending state, if a journal is executed you will not be able to delete. The alternative is to create a mirror journal entry to reverse the flow of funds.

Request #

N/A

Response #

204 - Success (No Content)

Error Codes #

404 - Journal Not Found
422 - Cannot Be Deleted

 

Edit Edit this page
© 2023 Alpaca Securities LLC All rights reserved.
© 2023 Alpaca Crypto LLC All rights reserved.
© 2023 AlpacaDB, Inc. All rights reserved.

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

Cryptocurrency services are made available by Alpaca Crypto LLC ("Alpaca Crypto"), a FinCEN registered money services business (NMLS # 2160858), and a wholly-owned subsidiary of AlpacaDB, Inc. Alpaca Crypto is not a member of SIPC or FINRA. Cryptocurrencies are not stocks and your cryptocurrency investments are not protected by either FDIC or SIPC. Please see the Disclosure Library for more information.

This is not an offer, solicitation of an offer, or advice to buy or sell securities or cryptocurrencies, or open a brokerage account or cryptocurrency account in any jurisdiction where Alpaca Securities or Alpaca Crypto respectively, are not registered or licensed, as applicable.