美国 IPO（首次公开募股）

美国 IPO 概述

Alpaca 提供广泛的美国 IPO 发行渠道，使合作伙伴能够在 IPO 上市时、股票在二级市场上市之前购买股票。

IPO API 提供：

• IPO 发行的只读发现
• 通过现有 Broker API 进行订单下达和管理
• 通过服务器发送事件（SSE）获取实时发行更新

订单管理

美国 IPO 仅接受名义金额（美元金额）的 GTC 订单。最终用户可以在每个 IPO 发行在 API 中可用后提交一个有条件买入订单（COB）。该订单可以在 60 分钟窗口结束前修改/取消。

IPO 不支持碎股。

IPO 时间线示例

以下是 IPO 时间线示例。请注意，并非所有 IPO 都遵循此时间线，且它们始终可能变更。

认证

身份验证使用与 Broker API 相同的 Alpaca OAuth 2.0 持有者令牌。无需更改。

示例头：

Authorization: Bearer <token>

更多信息，请参阅身份验证。

属性

端点

列出 IPO 发行

GET /v1/ipos

检索分页的 IPO 发行列表。

关于发行的说明：

两个发行可以共享相同的 ticker_symbol，但具有不同的 ipo_reference,availability。如果发行人在上市后取消或推迟交易，并且经过足够时间（财务状况变化、招股说明书变更等），就可能发生这种情况。在这种情况下，IPO 参考将不同，但代码仍相同。

参数

示例请求

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v1/ipos?availability=available&limit=50"

示例响应（200）

{
  "data": [
    {
      "name": "Example Corp",
      "description": "Example business description",
      "ticker_symbol": "EXMP",
      "ipo_reference": "EXMP260615",
      "cusip_id": "123456789",
      "prospectus_url": "https://example.com/prospectus.pdf",
      "offering_type": "IPO",
      "availability": "available",
      "anticipated_shares": 1000000,
      "max_price": "25",
      "min_price": "20",
      "trade_date": "2026-06-15",
      "settlement_date": "2026-06-16",
      "no_new_orders": false,
      "underwriters": ["Bank A", "Bank B"],
      "min_ticket_size": "100",
      "max_ticket_size": "10000"
    }
  ],
  "next_page_token": null
}

关于示例的说明：

• unit_step_size 被省略，因为此发行不强制执行步长约束。
• sixty_minute_expiration_time 缺失，因为 60 分钟撤回窗口尚未开始。
• 数值字段（min_price、max_price、min_ticket_size 等）是十进制字符串，无固定精度——不要假定为两位小数格式。
• ipo_reference 是不透明的；不要解析或假定其具体形态。

按 ID 获取 IPO

GET /v1/ipos/{ipo_reference}

通过参考 ID 检索单个 IPO 发行。

示例请求

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v1/ipos/EXMP260615"

示例响应（200）

{
  "data": {
    "name": "Example Corp",
    "description": "Example business description",
    "ticker_symbol": "EXMP",
    "ipo_reference": "EXMP260615",
    "cusip_id": "123456789",
    "prospectus_url": "https://example.com/prospectus.pdf",
    "offering_type": "IPO",
    "availability": "available",
    "anticipated_shares": 1000000,
    "max_price": "25",
    "min_price": "20",
    "trade_date": "2026-06-15",
    "settlement_date": "2026-06-16",
    "no_new_orders": true,
    "sixty_minute_expiration_time": "2026-06-15T13:00:00Z",
    "underwriters": ["Bank A", "Bank B"],
    "unit_step_size": "1",
    "min_ticket_size": "100",
    "max_ticket_size": "10000"
  }
}

此示例适用于处于 60 分钟撤回窗口内的发行——注意 no_new_orders: true 以及已填充的 sixty_minute_expiration_time。

下达 IPO 订单

IPO 订单通过标准 Broker API 订单端点下达。订单请求和响应使用标准 Order schema——有关完整的请求和响应字段集，请参阅创建账户订单参考文档。以下字段是 IPO 特定的注意事项。

IPO 特定订单规则

• 使用 ipo_reference（发行参考）作为订单请求中的 symbol 字段。
• IPO 订单仅接受名义金额：提供 notional；省略 qty。在响应中，IPO 订单的 qty 始终为 null。
• IPO 仅接受 side=buy。
• type 必须为 market。
• time_in_force 必须为 gtc——仅在发行期和 60 分钟撤回窗口内有效。
• 订单会根据发行约束进行验证（min_ticket_size、max_ticket_size，以及存在时的 unit_step_size）。
• 响应中的 asset_class 为 "ipo"。

下达 IPO 订单

POST /v1/trading/accounts/{account_id}/orders

仅在发行处于 availability=available 且 60 分钟撤回窗口开始之前（no_new_orders=false）才可以下新订单。在 60 分钟窗口开始后提交的订单可能会同步受理，之后通过交易事件 SSE 流拒绝——详情请参见错误处理。

示例请求

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://broker-api.alpaca.markets/v1/trading/accounts/{account_id}/orders" \
  -d '{
    "symbol": "EXMP260615",
    "side": "buy",
    "type": "market",
    "time_in_force": "gtc",
    "notional": "1000",
    "client_order_id": "my-unique-order-123"
  }'

示例响应（200）

响应是一个标准 Order 对象。需重点关注的 IPO 特定字段：

{
  "id": "b50c01d4-3d71-4295-8426-93c953c1ceb6",
  "client_order_id": "my-unique-order-123",
  "status": "new",
  "asset_class": "ipo",
  "symbol": "EXMP260615",
  "notional": "1000",
  "qty": null,
  "side": "buy",
  "type": "market",
  "time_in_force": "gtc",
  "created_at": "2026-06-09T15:30:00.000Z",
  "submitted_at": "2026-06-09T15:30:00.000Z"
}

完整响应还包含标准 Order 字段（updated_at、filled_at、filled_qty、filled_avg_price、expired_at、canceled_at、failed_at、replaced_at、replaced_by、replaces、asset_id、order_class、order_type、position_intent、limit_price、stop_price、extended_hours、legs、trail_percent、trail_price、hwm、subtag、source）。有关规范 schema，请参阅创建账户订单参考文档。

替换 IPO 订单

PATCH /v1/trading/accounts/{account_id}/orders/{order_id}

有关完整 schema，请参阅替换账户订单参考文档。对于 IPO 订单，请求体中只有 notional 和 client_order_id 有意义。在整个发行期和 60 分钟撤回窗口内均接受修改——一旦撤回窗口结束，COB 即具有约束力，不再允许修改。

示例请求

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://broker-api.alpaca.markets/v1/trading/accounts/{account_id}/orders/{order_id}" \
  -d '{
    "notional": "1500"
  }'

修改窗口关闭后的拒绝

在修改窗口关闭后提交的替换请求目前同步受理（HTTP 200），并稍后通过交易事件 SSE 流拒绝——请参见异步拒绝。交易事件作为 rejected 事件到达，其内部 order.reason 引用已关闭的修改窗口。订阅交易事件流以向最终用户呈现此最终状态。

取消 IPO 订单

DELETE /v1/trading/accounts/{account_id}/orders/{order_id}

请参阅删除账户订单参考文档。在整个发行期和 60 分钟撤回窗口内均接受取消——一旦撤回窗口结束，COB 即具有约束力，不再允许取消。

示例请求

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v1/trading/accounts/{account_id}/orders/{order_id}"

获取 IPO 订单

GET /v1/trading/accounts/{account_id}/orders/{order_id}

检索 IPO 订单的当前状态。返回标准 Order schema——请参阅获取账户订单。

示例请求

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v1/trading/accounts/{account_id}/orders/{order_id}"

示例响应（200）

下面显示的是 IPO 特定字段；完整响应包括所有标准 Order 字段。

{
  "id": "b50c01d4-3d71-4295-8426-93c953c1ceb6",
  "client_order_id": "my-unique-order-123",
  "status": "new",
  "asset_class": "ipo",
  "symbol": "EXMP260615",
  "notional": "1000",
  "qty": null,
  "filled_qty": "0",
  "filled_avg_price": null,
  "side": "buy",
  "type": "market",
  "time_in_force": "gtc",
  "created_at": "2026-06-09T15:30:00.000Z",
  "submitted_at": "2026-06-09T15:30:00.000Z",
  "filled_at": null
}

列出 IPO 订单

GET /v1/trading/accounts/{account_id}/orders

列出账户的订单，可选按 IPO 代码过滤。使用标准列出账户订单端点和参数集。

参数

示例请求

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v1/trading/accounts/{account_id}/orders?symbols=EXMP260615"

订单状态流

IPO 订单遵循特定的生命周期：

典型流程：

1. 订单下达 → pending_new（短暂）
2. 受理 → new
3. 收到分配 → filled（填充 filled_qty 和 filled_avg_price）

注意： 全天候 24/7 可用，因此订单在受理后立即从 pending_new 转为 new。订单保持 new 状态，直到发行结束并分配额度。pending_new 状态是瞬态的，应在几秒内解决。

重要： 状态 held、accepted、pending_cancel 和 pending_replace 不属于标准 IPO 订单生命周期。如果你观察到这些状态持续存在，可能表明存在问题。

异步拒绝

某些拒绝条件不会在提交时同步评估，而是稍后作为 rejected 事件在交易事件 SSE 流（GET /v2/events/trades）上传递。最常见的情况是：

• 对已进入 60 分钟撤回窗口（no_new_orders=true）的发行提交新订单——订单被受理为 pending_new 并异步拒绝。
• 在修改窗口关闭后替换或取消订单——请求同步受理并异步拒绝。
• 受理后失败的账户级资格检查。
• 分配时的拒绝（例如重复订单、分配引擎约束）。

始终在订阅 IPO 事件流的同时订阅交易事件流，以向最终用户呈现这些最终状态变更。

IPO 头寸

一旦 IPO 分配给最终用户，它就会以 asset_class: "us_equity" 出现在标准头寸端点上。有关完整 schema，请参阅头寸 API 参考。

生命周期

与头寸可见性相关的有三种生命周期状态：

1. 分配前。 当订单仍处于 new / pending_new 时，不存在头寸记录——尚无成交。
2. 分配后、二级市场上市前。 一旦分配送达，就会出现头寸记录，其中 qty、qty_available、avg_entry_price 和 cost_basis 由分配填充。在此窗口内，市场数据派生字段不可用，因为该证券尚未在二级市场开始交易——请参见下文。
3. 二级市场交易开始后。 该证券的定价源激活；市场数据字段在后续读取时正常填充。

上市前窗口的市场数据字段

当头寸处于分配后、二级市场上市前窗口时，以下字段返回为 null：

• market_value
• unrealized_pl、unrealized_plpc
• unrealized_intraday_pl、unrealized_intraday_plpc
• current_price、lastday_price、change_today
• exchange 返回为空字符串

此窗口内填充的字段为：

• asset_class: "ipo"
• symbol（即 ipo_reference）
• qty、qty_available（已分配的股数）
• avg_entry_price、cost_basis（源自最终分配价格）
• side

建议： 在渲染已分配但尚未上市的 IPO 头寸时，对于通常显示当前价格的任何 UI 单元格，回退使用 avg_entry_price，并在二级市场交易开始前将未实现盈亏视为零。

示例响应（200）——上市前 IPO 头寸

{
  "asset_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "symbol": "EXMP260615",
  "exchange": "",
  "asset_class": "ipo",
  "qty": "100",
  "qty_available": "100",
  "side": "long",
  "avg_entry_price": "20",
  "cost_basis": "2000",
  "market_value": null,
  "current_price": null,
  "lastday_price": null,
  "change_today": null,
  "unrealized_pl": null,
  "unrealized_plpc": null,
  "unrealized_intraday_pl": null,
  "unrealized_intraday_plpc": null
}

服务器发送事件（SSE）

GET /v2/events/ipos

流式传输实时 IPO 更新，包括发行变更、可用性更新、分配和时间线里程碑。

查询参数

事件类型

关于动词大小写的说明： verb 值为 PascalCase（例如 Offering、SixtyMinMail）。过滤事件时须精确匹配。

可见性：

• 广播事件发送给所有连接的客户端。
• 按账户事件仅过滤到接收该分配的特定账户。

沙箱限制： 沙箱环境目前不发出 Prospectus 事件。请在生产环境中测试 Prospectus 处理程序。

事件 Schema

所有事件遵循通用的信封结构：

{
  "verb": "Offering",
  "offering_reference": "EXMP260615",
  "event_id": "01JBPXJ4Z8XWQK3QY2Q5N9R8KT",
  "payload": {},
  "at": "2026-06-09T10:30:00.000Z",
  "received_at": "2026-06-09T10:30:00.000Z"
}

分配事件

分配事件在顶层（信封之外）包含额外的账户特定字段：

{
  "verb": "Allocation",
  "offering_reference": "EXMP260615",
  "event_id": "01JBPXJ4Z8XWQK3QY2Q5N9R8KT",
  "account_number": "511768662",
  "correspondent": "LPCA",
  "payload": {
    "cusip_id": "123456789",
    "final_price": "20",
    "allocated_shares": "100",
    "allocated_amount": "2000",
    "subject": "IPO Allocation: Example Corp"
  },
  "at": "2026-06-12T07:30:00.000Z",
  "received_at": "2026-06-12T07:30:00.000Z"
}

示例请求

# Live tail
curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v2/events/ipos"

# Replay events from a given date forward
curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  "https://broker-api.alpaca.markets/v2/events/ipos?since=2026-06-01"

示例事件负载

发行已创建：

data: {"verb":"Offering","offering_reference":"EXMP260615","event_id":"01JBPXJ4Z8XWQK3QY2Q5N9R8KT","payload":{"name":"Example Corp","ticker_symbol":"EXMP","offering_type_name":"IPO","available_to_order":"Available","min_price":"18","max_price":"22","source":"sync-offerings"},"at":"2026-06-09T10:30:00.000Z","received_at":"2026-06-09T10:30:00.000Z"}

payload.available_to_order 以 PascalCase 枚举字符串形式发出——为 "Available"、"NotAvailable" 或 "Closed" 之一。请注意，这与发行对象的 availability 字段的值空间不同，后者为小写（available / not_available / closed）。在两者之间映射时，请在客户端进行规范化。payload.source 标识上游同步来源（例如 "sync-offerings"）。视为仅供参考。

六十分钟邮件：

data: {"verb":"SixtyMinMail","offering_reference":"EXMP260615","event_id":"01JBPXJ4Z8XWQK3QY2Q5N9R8KT","payload":{"subject":"60-minute withdrawal window: Example Corp","sixty_minute_expiration_time":"2026-06-15 13:00:02 UTC"},"at":"2026-06-15T12:00:02.000Z","received_at":"2026-06-15T12:00:02.000Z"}

payload.sixty_minute_expiration_time 是形式为 YYYY-MM-DD HH:MM:SS UTC 的自由格式字符串——不是 RFC3339，也不与发行对象上的 sixty_minute_expiration_time 属性（为 RFC3339）格式相同。从 SSE 负载读取时，按显式的 YYYY-MM-DD HH:MM:SS UTC 布局解析。

发行取消：

data: {"verb":"OfferingCancellation","offering_reference":"EXMP260615","event_id":"01JBPXJ4Z8XWQK3QY2Q5N9R8KT","at":"2026-06-09T11:00:00.000Z","received_at":"2026-06-09T11:00:00.000Z"}

OfferingCancellation 事件不包含 payload。将其缺失视为空正文。

分配：

data: {"verb":"Allocation","offering_reference":"EXMP260615","event_id":"01JBPXJ4Z8XWQK3QY2Q5N9R8KT","account_number":"511768662","correspondent":"LPCA","payload":{"final_price":"20","allocated_shares":"100","allocated_amount":"2000"},"at":"2026-06-12T07:30:00.000Z","received_at":"2026-06-12T07:30:00.000Z"}

IPO 生命周期

响应头

说明

• 重连连接断开时：重新发出带有 since=<last-received-date> 的请求以重放你可能在断开期间错过的事件，然后使用 event_id 去重。
• 浏览器说明：原生 EventSource 不支持设置请求头；请使用 polyfill 或基于 fetch 的 SSE shim，以允许传递 Authorization 头。

SixtyMinMail 事件

此事件标志着生效日 60 分钟 COB（有条件买入订单）撤回/取消最终窗口的开始：

• 投资者可在此窗口内取消或修改订单。
• 60 分钟窗口开始后无法下新订单。
• 窗口结束后，COB 具有约束力。
• 考虑向最终用户发送额外的电子邮件通知以提供可审计性。

驱动 UI 倒计时： 一旦窗口开始，发行对象会公开 sixty_minute_expiration_time（RFC3339）——使用 SixtyMinMail SSE 事件作为进入倒计时 UI 的触发器，然后读取发行对象的 sixty_minute_expiration_time（或 SSE 负载中的 sixty_minute_expiration_time）获取截止时间。仅凭发行对象上的到期字段不能用作开始信号，因为当它出现时，窗口已经开始。

分页

• 在列表端点上使用 limit 和 page_token
• 在 200 响应中，如果还有更多结果，则返回 next_page_token
• 在后续请求中将 next_page_token 作为 page_token 传递

错误处理

错误来源

1. API 响应（同步）——服务器返回 HTTP 错误状态以及包含 code 和 message 的 JSON 正文。
2. 交易事件（SSE，异步）——订单被受理后，之后可能被拒绝。该拒绝通过账户的交易事件流（GET /v2/events/trades）传递——请参见上文的异步拒绝。

REST API 接口

出错时，API 返回：

• HTTP 状态： 400、401、403、404、422、429、500、501、503、504
• JSON 正文： code（number）、message（string）

示例：

{ "code": 40020012, "message": "IPO orders must specify notional and omit qty" }

通用错误代码（所有 API，包括 IPO）

适用于所有 Alpaca API 端点的相同错误代码和 HTTP 状态也适用于 IPO 端点。完整列表请参见主要 API 文档。

IPO 特定错误代码

IPO 订单创建和替换可能返回以下内容。HTTP 状态各异（400、404、422、500、501、429、503、504）。

常见情况说明

• 对已关闭发行提交返回 422 / 40010001 / "asset <symbol> is not active"。（availability=closed 的拒绝通过标准非活动资产代码呈现，而不是通过 42210000。）
• 提交非数字或格式错误的 notional 在请求验证层、IPO 特定检查运行之前返回 400 / 40010000 / "request body format is invalid"。
• 对处于 60 分钟撤回窗口内的发行提交（no_new_orders=true）会同步受理为 pending_new，之后通过交易事件 SSE 流拒绝——请参见异步拒绝。
• 在修改窗口关闭后替换或取消订单也同步受理，之后通过交易事件 SSE 流拒绝。目前没有同步的 40320060 / "modification window closed" 错误。

交易事件（SSE）

订单受理后的拒绝通过交易事件 SSE 流（GET /v2/events/trades）传递。每次拒绝作为 rejected 事件到达，其内部 order 对象携带标准订单字段，以及可用时的 reason 字符串。常见的 IPO 拒绝原因包括发行关闭、账户资格、重复订单和分配引擎结果——这些原因是自由文本，可能不同。

有关完整的事件信封、schema 和重连语义，请参阅订阅交易事件（SSE）参考文档。其中记录的 since / since_id 重放参数同样适用。

集成检查清单

1. 确保你的 OAuth 令牌具有所需的权限范围。
2. 实现 GET /v1/ipos 以发现可用发行；将 ipo_reference 视为不透明。
3. 下单时使用 ipo_reference 作为 symbol。
4. 使用仅名义金额订单（提供 notional，省略 qty）；side=buy、type=market、time_in_force=gtc。
5. 根据 min_ticket_size、max_ticket_size 以及存在时的 unit_step_size 验证订单（注意 unit_step_size 是可选的，可能缺失）。
6. 处理 60 分钟撤回窗口：一旦 no_new_orders=true 就停止允许新订单，并在 SixtyMinMail SSE 事件触发后使用 sixty_minute_expiration_time 显示倒计时。
7. 订阅 IPO 事件 SSE 流（GET /v2/events/ipos）以获取发行生命周期事件。过滤时使用 PascalCase 动词。
8. 订阅交易事件 SSE 流（GET /v2/events/trades）以获取异步订单拒绝（例如在 60 分钟窗口内提交的订单）。
9. 使用 since=<date> 实现重连逻辑以重放，并按 event_id（ULID）去重。
10. 处理上市前的 IPO 头寸：市场数据字段在分配与二级市场首笔交易之间为 null；在价格填充之前，从 avg_entry_price 渲染 UI 单元格。

投资首次公开募股（“IPO”）涉及重大风险，并非适合所有投资者。IPO 证券没有先前的公开交易历史，发行价可能不反映发行后的市场价格。IPO 证券的市场价格可能波动，投资者可能损失部分或全部投资。

有关 IPO 发行人的信息可能有限，发行人可能经营历史有限或未实现盈利。无法保证会形成活跃或流动的交易市场。

本材料仅供参考，不构成出售证券的要约或购买证券要约的招揽。任何要约将仅通过向美国证券交易委员会提交的招股说明书进行。投资者在投资前应仔细阅读招股说明书，包括其中描述的风险因素。