技能介绍

要解决什么

在 Alpaca 全权委托（omnibus）账户里，预注资的 firm / sweep 账户需要把现金或证券即时划给终端用户账户。逐个用户走外部银行转账，慢且成本高，"秒到账"体验完全做不到。日志（journal）就是这条内部通道：在你自己的账户之间转移价值，永不触碰外部银行体系（那是 alpaca-broker-funding-transfers 的职责）。Instant funding、cashback、share rewards 都建立在它之上。

核心能力与关键步骤

JNLC 与 JNLS 两种条目

JNLC：现金，USD，firm ↔ user 双向
JNLS：证券，整股或碎股，仅 firm → user

API 端点

POST /v1/journals：单条日志
POST /v1/journals/batch：一对多（仅 JNLC）
POST /v1/journals/reverse_batch：多对一（仅 JNLC）
GET /v1/journals：列表，支持 after / before / status 等过滤
DELETE /v1/journals/{journal_id}：取消
GET /v2/events/journals/status：SSE 状态流

幂等键

创建时传 Idempotency-Key（≤128 字符，建议客户端生成 UUID）。同 key 同 body 返回原日志，同 key 不同 body 返回 422。这是资金移动重试安全的正确做法——网络超时后盲目重试 POST /v1/journals 可能重复入账。建议从自有交易 ID 确定性生成 key。

批量原子性

批处理全有或全无：任一条校验失败（比如一个错误的 account ID），整批回滚。

状态生命周期

queued → sent_to_clearing → executed 是正常路径。但 executed 并非终态——Alpaca cashiering 仍可能撤销。真正的终态是 canceled / deleted / correct。

适用边界与注意点

资格：cash-pooling / journals 用例需要 Alpaca 审核，可能涉及本地牌照，需咨询法务
JNLS 的 to_account 必须 ACTIVE，from_account 可 ACTIVE 或 CLOSE
余额不足时 create 返回 403
日限额触发会推到 pending 等待人工审批
列表超过 10 万条返回 422，必须用 after / before / limit 过滤
删除仅对 pending 有效（204）；要撤销已执行日志，建一条反向镜像日志，不要尝试 delete
correct 会新建一个 journal ID，原 ID 变为 canceled/correct——按 journal ID 对账时要同时处理两个 ID
Travel Rule：资金移动日志要带 transmitter 信息
沙箱可用 description 字段放 fixture（如 /fixtures/status=rejected/fixtures/）模拟 rejected / pending 场景