alpaca-broker-journals

Alpaca Broker API — 账务划转

账务划转会在你自己的 Alpaca 综合账户中的两个账户之间转移价值——通常是在预先注资的公司／归集账户与用户账户之间进行。这是“即时注资”、返现和股票奖励背后的核心机制。它们不会涉及外部银行业务（相关内容见 alpaca-broker-funding-transfers）。

请先阅读 alpaca-broker-integration，了解基础 URL 和身份验证（客户端凭据 Bearer 令牌；旧版 Basic 仍可使用）。

参考资料

• 指南：https://docs.alpaca.markets/docs/funding-via-journals
• API 参考：https://docs.alpaca.markets/reference/createjournal
• 实时架构：alpaca-docs MCP → get-endpoint 标题为 "Broker API"，路径为 /v1/journals

1. 端点

方法	路径	用途
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}	取消待处理的账务划转（204）
GET	/v2/events/journals/status	SSE 账务划转状态流（v1 已弃用）

2. JNLC 与 JNLS

entry_type 必须严格为 "JNLC" 或 "JNLS"。

• JNLC — 现金。 在账户之间转移 USD。允许公司账户 ↔ 用户账户，两个方向均可。不支持客户之间转账。
• JNLS — 证券。 转移整数或零碎股。仅允许公司账户 → 用户账户。用于注册／推荐股票奖励。

// 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" }

字段	JNLC	JNLS	备注
from_account / to_account	必填	必填	账户 UUID
amount	必填	—	十进制字符串
symbol / qty	—	必填	qty 为字符串；允许零碎股
currency	可选	可选	无已记录的默认值
description	可选	可选	≤1024 个字符；接受沙盒测试数据
transmitter_*	可选（JNLC）	不适用	旅行规则字段

响应： 200 账务划转 · 403 金额／资产不可用 · 404 未找到账户 · 422 幂等键与不同请求正文重复使用。

3. Idempotency-Key 标头——务必使用

创建账务划转时，请传入 Idempotency-Key 标头（≤128 个字符；建议使用客户端生成的 UUID）。

• 相同的键 + 完全相同的请求正文 → 返回原账务划转记录（不会重复执行）。
• 相同的键 + 不同的请求正文 → 422。

**经验：**这是确保资金转移可安全重试的正确方法。如果不使用该标头，POST /v1/journals 遇到网络超时后，你将无法确定现金是否已转移；盲目重试可能导致重复注资。请根据自己的交易 ID 确定性地生成键，并在每次尝试时都发送该键。

4. 批量与反向批量（仅限 JNLC，全有或全无）

批量——一对多（将归集账户的资金分发给多个用户）：

{ "entry_type": "JNLC", "from_account": "<firm-uuid>",
  "entries": [ { "to_account": "<u1>", "amount": "1000" }, { "to_account": "<u2>", "amount": "250" } ] }

反向批量——多对一（从多个用户账户向公司账户收回现金）：

{ "entry_type": "JNLC", "to_account": "<firm-uuid>",
  "entries": [ { "from_account": "<u1>", "amount": "10" }, { "from_account": "<u2>", "amount": "100" } ] }

每条记录都必须通过验证，否则整个批次都会失败（一个错误的账户 ID 就会导致整个批次失败）。此后两者的行为有所不同：/batch 接受 Idempotency-Key，并返回 BatchJournalResponse（Journal 对象，以及每条失败记录对应的 error_message）；而 /reverse_batch 的文档中没有说明此类机制——它会返回不含逐条错误信息的普通 JNLC 数组，因此请在本地防止反向批量请求被重复处理。

5. 状态生命周期

JournalStatus：queued、sent_to_clearing、pending、executed、activity_created、rejected、canceled、refused、deleted、correct。

正常流程取决于 Alpaca 为你设置的 JNLC 版本。 JNLS 和 JNLC v1：queued → sent_to_clearing → executed。JNLC v2（仅限单笔现金日记账；批次仍使用 v1）：创建响应通常会直接返回 executed，随后出现 activity_created；只有在手动审批流程中才会出现 sent_to_clearing。无论哪种情况，都要接受全部十种状态——executed 才表示购买力已发生变动。

状态	含义	终止状态
queued	排队中	否
sent_to_clearing	已提交至账簿和记录	否
pending	需要 Alpaca 运营团队审批（通常是 JNLC 限额所致——参见 §7）	否
executed	余额已更新——但并非最终状态，出纳操作仍可将其冲回	否（非最终状态）
activity_created	已创建非交易活动（仅限 JNLC v2）；仅供参考，仍可冲回	否（非最终状态）
rejected	已被手动拒绝	否
refused	未通过初步检查；从未记入账本（例如，快速重放未通过余额检查）	否
canceled	已通过 API/运营操作取消	最终状态
deleted	已从账本中移除	最终状态
correct	先前已执行的日记账已取消，并以更正后的金额重新创建	最终状态

两点重要经验：

1. executed ≠ 最终状态。 不要将 executed 视为不可逆——Alpaca 出纳操作可以冲回未获准的日记账。请结合后续事件进行对账。
2. correct 会创建一个新的日记账 ID。 更正会取消原记录，并以更正后的金额创建一条新日记账——并非在原记录上直接修改。如果按日记账 ID 对账，原 ID 会变为 correct/已取消，而另一个 ID 才对应实际资金。两者都要处理。（因此事件使用者必须具备幂等性，并以 ID 为键——参见 alpaca-broker-reconciliation-idempotency。）

6. SSE 日记账事件

GET /v2/events/journals/status 会推送 JournalStatusEventV2：event_id（ULID，可排序）、journal_id、entry_type、status_from、status_to、description、idempotency_key、idempotency_key_type（single|batch）、batch_error_message。重放规则：设置 until 时必须提供 since；设置 until_id 时必须提供 since_id；不能同时使用 since 和 since_id。如果没有 since/since_id，则不会返回历史记录。参见 alpaca-broker-sse-events。

7. 限制与注意事项

• 资格要求： 资金池/日记账用例需要经过 Alpaca 审核，也可能需要当地许可证——请咨询法律顾问。
• JNLS 账户状态： to_account 必须为 ACTIVE；from_account 必须为 ACTIVE 或 CLOSE。
• 资金充足： 创建 JNLC 日记账时，如果金额不可用，则返回 403；反向批次操作返回 403 表示余额/资产不足。
• JNLC 限额会使状态变为 pending（需要运营团队手动审批）：单笔交易限额（默认 $50）和每日汇总限额（默认 $1,000）。两者均可配置；超限日记账会在次日的 BOD 作业中执行。
• 在交易账户上预先检查 cash_transferable——它表示“可转账现金（JNLC）”，与 cash 不同，后者会计入尚未结算的卖出所得。
• 如果结果集超过 100,000 条记录，GET /v1/journals 会返回 422——务必使用 after/before/limit 进行筛选。
• 仅待处理状态可删除： 只有状态为 pending 时，DELETE 才会成功（204）；已执行的日记账会返回 422。要冲回已执行的日记账，应创建方向相反的镜像日记账，不要尝试删除。
• 旅行规则： 在涉及资金转移的日记账中包含汇款人信息（所有入金均需提供，无论金额多少）。
• 沙盒夹具： 将夹具路径放入 description（例如 /fixtures/status=rejected/fixtures/），以便在测试中模拟 rejected/pending 结果。

8. 归集账户注资模式（为什么存在账务划转）

规范的 Broker API 注资架构：

Bulk external wire ──> FIRM / SWEEP account (pre-funded) ──JNLC──> user accounts (instant)
user account ──JNLC──> FIRM account ──external wire/ACH──> outside world (withdrawal)

你可以按自己的方式收款，将资金存放在公司账户中，然后立即将资金划转给用户，而不是为每位用户发起外部转账。提现则反向操作。这让你能够在缓慢的银行结算渠道之上，实现“即时入金”的用户体验。

相关技能： 外部资金转入/转出 → alpaca-broker-funding-transfers；重试安全性与更正 → alpaca-broker-reconciliation-idempotency；小数处理 → alpaca-broker-money-precision；事件 → alpaca-broker-sse-events。