This API provides a WebSocket stream for real-time market data. This allows you to receive the most up-to-date market information, which can be used to power your trading strategies.

The WebSocket stream provides real-time updates of the following market data:

• Stocks
• News

Steps to use the stream

To use the WebSocket stream follow these steps:

Connection

To establish a connection use the stream URL depending on the data you'd like to consume. The general schema of the URL is

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

Sandbox URL:

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

Any attempt to access a data feed not available for your subscription will result in an error during authentication.

Upon successfully connecting, you will receive the welcome message:

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

If you authenticated on the handshake (recommended below), authenticated follows without sending a message.

Authentication

Get an access token as described on the Authentication page. Use that same token here. Pick one method; do not send a handshake header and an auth frame.

Recommended: handshake header

Send the token on the WebSocket opening handshake:

wscat -c wss://stream.data.giftcity.in.alpaca.markets/v2/test \
  -H "Authorization: Bearer {TOKEN}"

You will receive connected then authenticated. No auth frame.

A missing Authorization header is fine (use the first-frame method below). If the header is present but not a valid Bearer token, the handshake fails with HTTP 401 and the WebSocket does not open.

Alternative: first-frame message

If you do not send Authorization on the handshake, authenticate within 10 seconds:

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

Invalid credentials on this path return a WebSocket error 402 auth failed.

Authentication response

After successful authentication, the server responds:

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

Subscription

Congratulations, you are ready to receive real-time market data!

You can send one or more subscription messages. The general format of the subscribe message is this:

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

You can subscribe to a particular symbol or to every symbol using the * wildcard. A subscribe message should contain what subscription you want to add to your current subscriptions in your session so you don’t have to send what you’re already subscribed to.

For example in the test stream, you can send this message:

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

The available channels are described for each streaming endpoints separately.

Much like subscribe you can also send an unsubscribe message that subtracts the list of subscriptions specified from your current set of subscriptions.

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

After subscribing or unsubscribing you will receive a message that describes your current list of subscriptions.

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

You will always receive your entire list of subscriptions, as illustrated by the sample communication excerpt below:

> {"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"]}]

Messages

Format

Every message you receive from the server will be in the format:

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

Control messages (i.e. where T is error, success or subscription) always arrive in arrays of size one to make their processing easier.

Data points however may arrive in arrays that have a length that is greater than one. This is to facilitate clients whose connection is not fast enough to handle data points sent one by one. Our server buffers the outgoing messages but slow clients may get disconnected if their buffer becomes full.

Content type

You can use the Content-Type header to switch between text and binary message data frame:

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

Encoding and Compression

Messages over the websocket are in encoded as clear text.

To reduce bandwidth requirements we have implemented compression as per RFC-7692. Our SDKs handle this for you so in most cases you won’t have to implement anything yourself.

Errors

Handshake auth failures return HTTP 401 and the WebSocket does not open. First-frame auth failures arrive as a WebSocket message with code 402.

You may also receive an error during your session. Below are the general errors you may run into.

Example

Here's a complete example of the test stream using the wscat cli tool. {TOKEN} is the access_token from the token endpoint.

$ wscat -c wss://stream.data.giftcity.in.alpaca.markets/v2/test \
    -H "Authorization: Bearer {TOKEN}"
Connected (press CTRL+C to quit)
< [{"T":"success","msg":"connected"}]
< [{"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}]