/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 for base URLs and auth (client-credentials Bearer token; legacy Basic still works).

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 | no documented default | | `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). They diverge after that: `/batch` accepts `Idempotency-Key` and returns `BatchJournalResponse` (the Journal object + an `error_message` per entry that failed), while `/reverse_batch` documents neither — it returns a plain array of `JNLC` with no per-item error, so guard reverse-batch replays locally.

5. Status lifecycle

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

**Happy path depends on the JNLC version Alpaca has set for you.** JNLS and JNLC v1: `queued → sent_to_clearing → executed`. JNLC v2 (single cash journals only; batches still run v1): the create response frequently comes back already `executed`, then `activity_created` follows, and `sent_to_clearing` appears only on the manual-approval path. Accept all ten statuses either way — `executed` is the one that means buying power moved.

| Status | Meaning | Terminal | |--------|---------|----------| | `queued` | In queue | no | | `sent_to_clearing` | Submitted to books-and-records | no | | `pending` | Needs Alpaca ops approval (usually a JNLC limit — see §7) | no | | `executed` | Balances updated — **but NOT final**, can still be reversed by cashiering | no (not final) | | `activity_created` | Non-trade activity created (JNLC v2 only); informational, still reversible | 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 lesso