alpaca-broker-journals

name

alpaca-broker-journals

description

Move cash (JNLC) and securities (JNLS) BETWEEN accounts inside your own Alpaca omnibus via the Broker API — single, batch, and reverse-batch journals, the Idempotency-Key header, journal status lifecycle including corrections, and the firm/sweep-account pattern that powers instant funding and share rewards. Use for internal account-to-account movement in any language. For deposits/withdrawals to EXTERNAL banks, use funding-transfers instead.

Alpaca Broker API — Journals

Journals move value between two accounts within your own Alpaca omnibus — typically between a pre-funded firm/sweep account and a user account. They are the engine behind "instant funding," cashback, and share rewards. They never touch the outside banking world (that's alpaca-broker-funding-transfers).

Read alpaca-broker-integration first. Broker API + HTTP Basic auth.

Reference

• Guide: https://docs.alpaca.markets/docs/funding-via-journals
• API ref: https://docs.alpaca.markets/reference/createjournal
• Live schema: alpaca-docs MCP → get-endpoint title "Broker API" path /v1/journals

1. Endpoints

Method	Path	Purpose
POST	/v1/journals	Single journal (JNLC cash or JNLS shares)
POST	/v1/journals/batch	One source → many destinations (JNLC only)
POST	/v1/journals/reverse_batch	Many sources → one destination (JNLC only)
GET	/v1/journals	List (filters: after, before, status, entry_type, to_account, from_account, limit)
GET	/v1/journals/{journal_id}	Retrieve one
DELETE	/v1/journals/{journal_id}	Cancel a pending journal (204)
GET	/v2/events/journals/status	SSE journal status stream (v1 is legacy)

2. JNLC vs JNLS

entry_type is exactly "JNLC" or "JNLS".

• JNLC — cash. Moves USD between accounts. Allowed firm ↔ user, both directions. Not customer-to-customer.
• JNLS — securities. Moves whole/fractional shares. Allowed firm → user only. Used for signup/referral share rewards.

// JNLC (cash)
{ "entry_type": "JNLC", "from_account": "<firm-uuid>", "to_account": "<user-uuid>", "amount": "100.00" }

// JNLS (shares)
{ "entry_type": "JNLS", "from_account": "<firm-uuid>", "to_account": "<user-uuid>", "symbol": "AAPL", "qty": "0.5" }

Field	JNLC	JNLS	Notes
from_account / to_account	required	required	account UUIDs
amount	required	—	decimal string
symbol / qty	—	required	qty is a string; fractional allowed
currency	optional	optional	defaults USD
description	optional	optional	≤1024 chars; accepts sandbox fixtures
transmitter_*	optional (JNLC)	n/a	Travel Rule fields

Responses: 200 journal · 403 amount/assets not available · 404 account not found · 422 idempotency-key reused with a different body.

3. Idempotency-Key header — USE IT

Pass an Idempotency-Key header (≤128 chars; a client-generated UUID is recommended) on journal creates.

• Same key + identical body → returns the original journal (no duplicate).
• Same key + different body → 422.

Lesson: this is the correct way to make money movement retry-safe. Without it, a network timeout on POST /v1/journals leaves you unsure whether the cash moved — and a blind retry can double-fund. Generate the key deterministically from your own transaction ID and send it on every attempt.

4. Batch vs reverse-batch (JNLC only, all-or-nothing)

Batch — one-to-many (fan a sweep account out to many users):

{ "entry_type": "JNLC", "from_account": "<firm-uuid>",
  "entries": [ { "to_account": "<u1>", "amount": "1000" }, { "to_account": "<u2>", "amount": "250" } ] }

Reverse batch — many-to-one (pull cash from many users back to the firm account):

{ "entry_type": "JNLC", "to_account": "<firm-uuid>",
  "entries": [ { "from_account": "<u1>", "amount": "10" }, { "from_account": "<u2>", "amount": "100" } ] }

Every entry must validate or the entire batch fails (one bad account ID kills it). The response is an array of BatchJournalResponse (the Journal object + an error_message per entry that failed). Idempotency-Key is supported with the same semantics.

5. Status lifecycle

JournalStatus: queued, sent_to_clearing, pending, executed, rejected, canceled, refused, deleted, correct.

Happy path: queued → sent_to_clearing → executed.

Status	Meaning	Terminal
queued	In queue	no
sent_to_clearing	Submitted to books-and-records	no
pending	Needs Alpaca ops approval (e.g. hit a JNLC daily limit)	no
executed	Balances updated — but NOT final, can still be reversed by cashiering	no (not final)
rejected	Manually rejected	no
refused	Failed preliminary checks; never hit the ledger (e.g. a fast replay failing the balance check)	no
canceled	Canceled via API/ops	FINAL
deleted	Removed from ledger	FINAL
correct	A prior executed journal was cancelled and re-created with a corrected amount	FINAL

Two critical lessons:

1. executed ≠ final. Don't treat executed as irreversible — Alpaca cashiering can reverse a journal that wasn't permitted. Reconcile against later events.
2. correct creates a NEW journal ID. A correction cancels the original and issues a new journal with the corrected amount — it is not an in-place edit. If you reconcile by journal ID, the original ID transitions to correct/cancelled while a different ID carries the real funds. Handle both. (This is why event consumers must be idempotent and ID-keyed — see alpaca-broker-reconciliation-idempotency.)

6. SSE journal events

GET /v2/events/journals/status pushes JournalStatusEventV2: event_id (ULID, sortable), journal_id, entry_type, status_from, status_to, description, idempotency_key, idempotency_key_type (single|batch), batch_error_message. Replay rules: since required if until set; since_id required if until_id set; can't mix since with since_id. Without a since/since_id, no history is returned. See alpaca-broker-sse-events.

7. Constraints & gotchas

• Eligibility: the cash-pooling/journals use case requires Alpaca review and possibly a local license — check with counsel.
• JNLS account states: to_account must be ACTIVE; from_account must be ACTIVE or CLOSE.
• Sufficient funds: JNLC create → 403 if the amount isn't available; reverse-batch 403 = insufficient balance/assets.
• Daily limits push to pending (manual ops approval).
• GET /v1/journals returns 422 if the result set exceeds 100,000 records — always filter with after/before/limit.
• Delete is pending-only: DELETE succeeds (204) only when pending; an executed journal → 422. To reverse an executed journal, create a mirror journal in the opposite direction, don't try to delete it.
• Travel Rule: include transmitter info on money-moving journals (required on all incoming deposits regardless of amount).
• Sandbox fixtures: put fixtures in description (e.g. /fixtures/status=rejected/fixtures/) to simulate rejected/pending outcomes for testing.

8. The sweep-account funding pattern (why journals exist)

The canonical Broker API funding architecture:

Bulk external wire ──> FIRM / SWEEP account (pre-funded) ──JNLC──> user accounts (instant)
user account ──JNLC──> FIRM account ──external wire/ACH──> outside world (withdrawal)

You collect money your own way, hold it in a firm account, and journal it to users instantly rather than running a per-user external transfer. Withdrawals reverse the flow. This is what makes "instant deposit" UX possible on top of slow banking rails.

Related skills: external money in/out → alpaca-broker-funding-transfers; retry-safety & corrections → alpaca-broker-reconciliation-idempotency; decimal handling → alpaca-broker-money-precision; events → alpaca-broker-sse-events.