Alpaca 券商日志

要解决的问题

Broker API 里的「即时到账」没法靠外部银行转账实现——ACH 要走一两天，逐用户打款不现实。Journal 的解法是在你自己的 omnibus 内部做账本划转：先用自有渠道收款，把钱囤在 firm/sweep 账户，再通过 POST /v1/journals 瞬间记到用户头上。cashback、注册送股本质上都是 Journal。它不碰外部银行体系，外部出入金属于另一套 transfers 技能。

核心能力与工作方式

• 两种 entry_type：JNLC 走现金，firm ↔ user 双向；JNLS 走证券（含碎股），只能 firm → user，典型场景是推荐奖励送股。
• 幂等是硬要求：创建时必须带 Idempotency-Key（推荐 UUID）。相同 key + 相同 body 返回原记录；相同 key + 不同 body 报 422。超时后盲目重试会重复打款，正确做法是基于自己的交易 ID 确定性生成 key，每次重试复用。
• 批量划转：batch 一对多（sweep 分发给多个用户），reverse_batch 多对一（回收）。仅 JNLC，且全有或全无——一个坏 account ID 让整批失败。
• 状态要按终态处理：queued → sent_to_clearing → executed 是理想路径，但 executed 不是终态，cashiering 仍可撤销；真正的终态是 canceled / deleted / correct。correct 会取消原 Journal 并新建一条，ID 变了，对账要同时覆盖新旧两条。
• 事件流：GET /v2/events/journals/status 推送 SSE，事件带 ULID 的 event_id。since/since_id 必须与 until/until_id 成对出现，且不能混用 since 与 since_id；不带 since 参数就没有历史。
• 取消与撤销：DELETE 只对 pending 生效（204）；撤销已执行的 Journal 要反向建一条 mirror journal，不能删。

适用边界与注意点

• cash-pooling/journals 用途需 Alpaca 审核，可能还要当地牌照，先咨询法务。
• GET /v1/journals 结果超过 10 万条返回 422，必须用 after/before/limit 过滤。
• JNLC 余额不足直接 403；触达日限额会把 Journal 顶到 pending 等待人工审批。
• 资金类 Journal 要带 transmitter_* 的 Travel Rule 字段，入金不论金额都要。
• to_account 必须 ACTIVE；JNLS 的 from_account 可以是 CLOSE。