一、用途 Journals 在自有 Alpaca omnibus 内的两个账户之间划转价值，通常发生在公司/集中（sweep）账户与用户账户之间，是即时入金、返现和赠股的底层机制。它不涉及外部银行系统（外部出入金见 alpaca-broker-funding-transfers）。使用前需先阅读 alpaca-broker-integration，认证方式为 Broker API + HTTP Basic。
二、主要能力
- 端点：POST /v1/journals 单笔（JNLC 现金或 JNLS 证券）；POST /v1/journals/batch 一源多目标（仅 JNLC）；POST /v1/journals/reverse_batch 多源一目标（仅 JNLC）；GET /v1/journals 列表（可过滤 after、before、status、entry_type、to_account、from_account、limit）；GET /v1/journals/{journal_id} 单笔查询；DELETE /v1/journals/{journal_id} 取消待处理分录；GET /v2/events/journals/status 订阅 SSE 状态流（v1 为旧版）。
- JNLC 为现金，移动美元，允许 firm ↔ user 双向，不可用户对用户；JNLS 为证券，移动整数/碎股，仅允许 firm → user，常用于注册/推荐赠股。字段：from_account、to_account 必填；JNLC 必填 amount（十进制字符串），JNLS 必填 symbol 与 qty（字符串，允许碎股）；currency 默认为 USD，description 不超过 1024 字符；JNLC 支持 transmitter_* 旅行规则字段。
- 幂等：创建时传 Idempotency-Key（≤128 字符，建议客户端 UUID）。同 key 同 body 返回原分录，同 key 不同 body 返回 422。
- 批量均全有或全无：任一 entry 校验失败整批失败；返回 BatchJournalResponse 数组，含 Journal 对象与各条目的 error_message。
- 状态生命周期：queued、sent_to_clearing、pending、executed、rejected、canceled、refused、deleted、correct。canceled、deleted、correct 为终态。executed 并非最终，仍可能被 cashiering 冲正；correct 会取消原分录并以新 journal ID 重建，不是原地修改。
- SSE 事件 JournalStatusEventV2 含 event_id（ULID 可排序）、journal_id、entry_type、status_from、status_to、description、idempotency_key、idempotency_key_type（single|batch）、batch_error_message。
三、使用方式与限制 批量仅支持 JNLC。现金池/账簿用途需 Alpaca 审核，可能需当地牌照，请咨询律师。JNLS 的 to_account 必须 ACTIVE，from_account 须 ACTIVE 或 CLOSE。现金不足返回 403；命中每日限额会进入 pending 等待人工审批；GET /v1/journals 结果超过 10 万条返回 422，应使用过滤条件。DELETE 仅对 pending 成功（204），executed 返回 422，需用反向镜像分录冲正。SSE 重放规则：设置 until 时必须提供 since，设置 until_id 时必须提供 since_id，二者不可混用；不带 since/since_id 不返回历史。沙箱可在 description 中放 fixtures 以模拟 rejected/pending。典型模式：外部电汇进 firm 账户，再用 JNLC 即时划给用户；提现则反向操作。相关技能：外部出入金、对账幂等、金额精度、SSE 事件。