Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

alpaca-broker-journals

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.

alpacahq · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add alpacahq/alpaca-skills --skill alpaca-broker-journals

About this skill


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

MethodPathPurpose
POST/v1/journalsSingle journal (JNLC cash or JNLS shares)
POST/v1/journals/batchOne source → many destinations (JNLC only)
POST/v1/journals/reverse_batchMany sources → one destination (JNLC only)
GET/v1/journalsList (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/statusSSE 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" }
FieldJNLCJNLSNotes
from_account / to_accountrequiredrequiredaccount UUIDs
amountrequired—decimal string
symbol / qty—requiredqty is a string; fractional allowed
currencyoptionaloptionaldefaults USD
descriptionoptionaloptional≤1024 chars; accepts sandbox fixtures
transmitter_*optional (JNLC)n/aTravel 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.

StatusMeaningTerminal
queuedIn queueno
sent_to_clearingSubmitted to books-and-recordsno
pendingNeeds Alpaca ops approval (e.g. hit a JNLC daily limit)no
executedBalances updated — but NOT final, can still be reversed by cashieringno (not final)
rejectedManually rejectedno
refusedFailed preliminary checks; never hit the ledger (e.g. a fast replay failing the balance check)no
canceledCanceled via API/opsFINAL
deletedRemoved from ledgerFINAL
correctA prior executed journal was cancelled and re-created with a corrected amountFINAL

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), `

Read the complete source ↗