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
- any status =
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