Skip to main content

WebSocket 流

机器翻译译自英文（docs.alpaca.markets）本页 63 段已全部译完

此 API 提供用于实时市场数据的 WebSocket 流。这让你能够接收最新的市场信息，可用于驱动你的交易策略。

WebSocket 流提供以下市场数据的实时更新：

使用流的步骤

要使用 WebSocket 流，请按照以下步骤操作：

连接

要建立连接，请根据你想消费的数据使用流 URL。URL 的一般架构为

wss://stream.data.alpaca.markets/{version}/{feed}

沙盒 URL：

wss://stream.data.sandbox.alpaca.markets/{version}/{feed}

任何试图访问你订阅不可用的数据源的尝试都会在认证期间导致错误。

📘 测试流

我们提供了一条全天候可用的测试流，即使在非交易时段也可使用，地址为：

wss://stream.data.alpaca.markets/v2/test

试用此测试流时请使用股票代码 "FAKEPACA"。

成功连接后，你将收到欢迎消息：

[{"T":"success","msg":"connected"}]

🚧 连接数限制

用户到单个端点的连接数受用户订阅限制，但在许多订阅中（或未订阅时）该限制为 1。如果你尝试打开第二个连接，将收到以下错误：

[{"T":"error","code":406,"msg":"connection limit exceeded"}]

认证

你可以在 WebSocket 打开握手期间进行认证，或在连接后发送认证消息进行认证。

使用 HTTP 请求头认证

你可以在 WebSocket 打开握手期间进行认证。

Trading API

使用你的 Trading API key ID 和 secret key：

websocat wss://stream.data.alpaca.markets/v2/test \
  -H="APCA-API-KEY-ID: {KEY_ID}" \
  -H="APCA-API-SECRET-KEY: {SECRET_KEY}"

Broker API

推荐使用的 Broker API 认证方法是通过 Client Credentials 认证流程获取的访问令牌：

websocat wss://stream.data.alpaca.markets/v2/test \
  -H="Authorization: Bearer {ACCESS_TOKEN}"

旧版 Broker API 凭据可使用 HTTP Basic 认证：

websocat wss://stream.data.alpaca.markets/v2/test \
  -H="Authorization: Basic {BASE64_CREDENTIALS}"


{BASE64_CREDENTIALS} 是 {KEY_ID}:{SECRET_KEY} 字符串的 base64 编码。

Alpaca Connect

应用程序可以使用代表用户获取的 OAuth 访问令牌：

websocat wss://stream.data.alpaca.markets/v2/test \
  -H="Authorization: Bearer {OAUTH_ACCESS_TOKEN}"

通过消息认证

或者，你也可以在打开 WebSocket 连接后通过发送消息进行认证。你必须在 10 秒内完成认证。

Trading API

发送你的 Trading API key ID 和 secret key：

{"action":"auth","key":"{KEY_ID}","secret":"{SECRET_KEY}"}

Broker API

当使用通过客户端凭据流程获取的 AuthX 访问令牌时，使用字面字符串 access_token 作为 key：

{"action":"auth","key":"access_token","secret":"{ACCESS_TOKEN}"}

旧版 Broker API 凭据可继续发送 key ID 和 secret key：

{"action":"auth","key":"{KEY_ID}","secret":"{SECRET_KEY}"}

Alpaca Connect

对于 Alpaca Connect 应用，使用字面字符串 oauth 作为 key，并将用户的 OAuth 访问令牌作为 secret：

{"action":"auth","key":"oauth","secret":"{OAUTH_ACCESS_TOKEN}"}

认证响应

认证成功后，服务器会响应：

[{"T":"success","msg":"authenticated"}]

请记住，大多数用户只能有 1 个活跃的流连接。如果该连接正被另一个第三方应用使用，你将收到错误：406 以及 "connection limit exceeded" 消息。同样，如果用户希望从 API 或另一个第三方应用访问其流，也会收到相同的错误消息。

订阅

恭喜，你已准备好接收实时市场数据！

你可以发送一条或多条订阅消息。订阅消息的通用格式如下：

{
  "action": "subscribe",
  "<channel1>": ["<SYMBOL1>"],
  "<channel2>": ["<SYMBOL2>","<SYMBOL3>"],
  "<channel3>": ["*"]
}

你可以订阅特定股票代码，或使用 * 通配符订阅所有股票代码。订阅消息应包含你想在当前会话的订阅基础上新增的订阅内容，这样你就无需重复发送已订阅的内容。

例如在测试流中，你可以发送以下消息：

{"action":"subscribe","trades":["FAKEPACA"]}

可用频道会在每个流式端点中分别说明。

与订阅类似，你也可以发送取消订阅消息，从当前订阅集合中减去指定的订阅列表。

{"action":"unsubscribe","quotes":["FAKEPACA"]}

订阅或取消订阅后，你将收到一条描述你当前订阅列表的消息。

[{"T":"subscription","trades":["AAPL"],"quotes":["AMD","CLDR"],"bars":["*"],"updatedBars":[],"dailyBars":["VOO"],"statuses":["*"],"lulds":[],"corrections":["AAPL"],"cancelErrors":["AAPL"]}]

你始终会收到完整的订阅列表，如下方示例通信片段所示：

> {"action": "subscribe", "trades": ["AAPL"], "quotes": ["AMD", "CLDR"], "bars": ["*"]}
< [{"T":"subscription","trades":["AAPL"],"quotes":["AMD","CLDR"],"bars":["*"],"updatedBars":[],"dailyBars":[],"statuses":[],"lulds":[],"corrections":["AAPL"],"cancelErrors":["AAPL"]}]
...
> {"action": "unsubscribe", "bars": ["*"]}
< [{"T":"subscription","trades":["AAPL"],"quotes":["AMD","CLDR"],"bars":[],"updatedBars":[],"dailyBars":[],"statuses":[],"lulds":[],"corrections":["AAPL"],"cancelErrors":["AAPL"]}]

消息

格式

你从服务器收到的每条消息都将采用以下格式：

[{"T": "{message_type}", {contents}},...]

控制消息（即 T 为 error、success 或 subscription 的消息）始终以长度为 1 的数组形式到达，以便于处理。

然而，数据点可能以长度大于 1 的数组形式到达。这是为了方便那些连接速度不足以逐条处理数据点的客户端。我们的服务器会缓冲出站消息，但如果缓冲区已满，缓慢的客户端可能会被断开连接。

内容类型

你可以使用 Content-Type 请求头在文本和二进制消息数据帧之间切换：

  • Content-Type: application/json
  • Content-Type: application/msgpack

编码与压缩

通过 websocket 传输的消息以明文编码。

为降低带宽需求，我们按 RFC-7692 实现了压缩。我们的 SDK 会为你处理这一点，因此在大多数情况下你无需自行实现任何内容。

错误

在会话期间你可能会收到错误。以下是你可能遇到的通用错误。

代码消息描述
400invalid syntax你发送给服务器的消息不符合规范。
:warning: 如果订阅消息中的股票代码格式无效，也可能返回此错误。
401not authenticated你在认证之前尝试了订阅或取消订阅。
402auth failed你提供了无效的认证凭据。
403already authenticated你在当前会话中已成功完成认证。
404auth timeout你在连接后未能成功完成认证。连接后你只有几秒钟时间进行认证。
405symbol limit exceeded你发送的股票代码订阅请求将超出你的订阅套餐所设定的上限。此时你的股票代码订阅将与发送失败请求之前保持一致。
406connection limit exceeded你已达到订阅允许的会话数量。
407slow client如果你处理服务器发送的消息速度过慢，可能会收到此错误。请注意，为避免让缓慢连接永远保持活跃，并不保证此错误一定会在你被断开连接之前送达。
409insufficient subscription你尝试访问的数据源不在你的订阅套餐范围内。
410invalid subscribe action for this feed你尝试订阅流中不可用的频道，例如在期权流中订阅 bars，或在新闻流中订阅 trades。
500internal error我方发生了意外错误。如果出现此错误，请告知我们。

除此之外，还可能存在一些特定于端点的错误，例如在期权流中。

示例

以下是使用 wscat 命令行工具的完整测试流示例：

$ wscat -c wss://stream.data.alpaca.markets/v2/test
Connected (press CTRL+C to quit)
< [{"T":"success","msg":"connected"}]
> {"action":"auth","key":"<YOUR API KEY>","secret":"<YOUR API SECRET>"}
< [{"T":"success","msg":"authenticated"}]
> {"action":"subscribe","bars":["FAKEPACA"],"quotes":["FAKEPACA"]}
< [{"T":"subscription","trades":[],"quotes":["FAKEPACA"],"bars":["FAKEPACA"]}]
< [{"T":"q","S":"FAKEPACA","bx":"O","bp":133.85,"bs":4,"ax":"R","ap":135.77,"as":5,"c":["R"],"z":"A","t":"2024-07-24T07:56:53.639713735Z"}]
< [{"T":"q","S":"FAKEPACA","bx":"O","bp":133.85,"bs":4,"ax":"R","ap":135.77,"as":5,"c":["R"],"z":"A","t":"2024-07-24T07:56:58.641207127Z"}]
< [{"T":"b","S":"FAKEPACA","o":132.65,"h":136,"l":132.12,"c":134.65,"v":205,"t":"2024-07-24T07:56:00Z","n":16,"vw":133.7}]
AI 翻译查看英文原文