Getting Started

Polygon.io provides a standardized interface for streaming real-time stock, forex, and crypto data using the WebSocket protocol. Users can specify which WebSocket channels they want to consume by sending instructions in the form of actions. Our WebSockets emit events to notify the user when an event has occurred in a subscribed channel.

Access to different feeds varies depending on your subscription. These docs are customized to your version of the API and display your key and data, which only you can see. These docs demonstrate using WebSocket to interact with the API using standardized protocols over TCP.

Step 1: Connect

Your API key allows 1 simultaneous connection to each cluster (3 total at one time). If another connection attempts to connect, the current connection will be disconnected.

Connect to a cluster

Delayed:wscat -c wss://delayed.polygon.io/stocks

Real-Time:wscat -c wss://socket.polygon.io/stocks

On connection you will receive the following message:

[{
    "ev":"status",
    "status":"connected",
    "message": "Connected Successfully"
}]

Step 2: Authenticate

You must authenticate before you can make any other requests.

{"action":"auth","params":"********"}

On successful authentication you will receive the following message:

[{
    "ev":"status",
    "status":"auth_success",
    "message": "authenticated"
}]

Step 3: Subscribe

Once authenticated, you can request a stream. You can request multiple streams in the same request.

Once authenticated, you can request a stream.

{"action":"subscribe","params":"T.LPL"}

You can also request multiple streams from the same cluster.

{"action":"subscribe","params":"T.LPL,Q.MSFT"}

Some notes on Responses:

Things happen very quickly in the world of finance, which means a Polygon.io WebSocket client must be able to handle many incoming messages per second. Due to the nature of the WebSocket protocol, if a client is slow to consume messages from the server, Polygon.io’s server must buffer messages and send them only as fast as the client can consume them. To help prevent the message buffer from getting too long, Polygon.io may send more than one JSON object in a single WebSocket message. We accomplish this by wrapping all messages in a JSON array, and adding more objects to the array if the message buffer is getting longer. For example, consider a WebSocket message with a single trade event in it:

[
    {"ev":"T","sym":"MSFT","i":"50578","x":4,"p":215.9721,"s":100,"t":1611082428813,"z":3}
]

If your client is consuming a bit slow, or 2+ events happened in very short succession, you may receive a single WebSocket message with more than one event inside it, like this:

[
    {"ev":"T","sym":"MSFT","i":"50578","x":4,"p":215.9721,"s":100,"t":1611082428813,"z":3}, 
    {"ev":"T","sym":"MSFT","i":"12856","x":4,"p":215.989,"s":1,"c":[37],"t":1611082428814,"z":3}
]

Note that if a client is consuming messages too slowly for too long, Polygon.io’s server-side buffer may get too large. If that happens, Polygon.io will terminate the WebSocket connection. You can check your account dashboard to see if a connection was terminated as a slow consumer. If this happens to you consistently, consider subscribing to fewer symbols or channels.

$
|

Trades

ws
Real-time:wss://socket.polygon.io/stocks

Stream real-time trades for a given stock ticker symbol.

Parameters

Specify a ticker symbol or use * to retreive all tickers. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"T.{ticker}"}

Response Attributes
evenum [T]

The event type.


symstring

The ticker symbol for the given stock.


xinteger

The exchange ID. See Exchanges for Polygon.io's mapping of exchange IDs.


istring

The trade ID.


zinteger

The tape. (1 = NYSE, 2 = AMEX, 3 = Nasdaq).


pnumber

The price.


sinteger

The trade size.


carray [integer]

The trade conditions


tinteger

The Timestamp in Unix MS.


Response Object

{
 "ev": "T",
 "sym": "MSFT",
 "x": 4,
 "i": "12345",
 "z": 3,
 "p": 114.125,
 "s": 100,
 "c": [
  0,
  12
 ],
 "t": 1536036818784
}

Quotes

ws
Real-time:wss://socket.polygon.io/stocks

Stream real-time quotes for a given stock ticker symbol.

Parameters

Specify a ticker symbol or use * to retreive all tickers. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"Q.{ticker}"}

Response Attributes
evenum [Q]

The event type.


symstring

The ticker symbol for the given stock.


bxinteger

The bid exchange ID.


bpnumber

The bid price.


bsinteger

The bid size.


axinteger

The ask exchange ID.


apnumber

The ask price.


asinteger

The ask size.


cinteger

The condition.


tinteger

The Timestamp in Unix MS.


Response Object

{
 "ev": "Q",
 "sym": "MSFT",
 "bx": 4,
 "bp": 114.125,
 "bs": 100,
 "ax": 7,
 "ap": 114.128,
 "as": 160,
 "c": 0,
 "t": 1536036818784
}

Aggregates (Per Second)

ws
Delayed:wss://delayed.polygon.io/stocks
Real-time:wss://socket.polygon.io/stocks

Stream real-time second aggregates for a given stock ticker symbol.

Parameters

Specify a ticker symbol or use * to retreive all tickers. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"A.{ticker}"}

Response Attributes
evenum [A]

The event type.


symstring

The ticker symbol for the given stock.


vinteger

The tick volume.


avinteger

Today's accumulated volume.


opnumber

Today's official opening price.


vwnumber

Today's volume weighted average price.


onumber

The opening tick price for this aggregate window.


cnumber

The closing tick price for this aggregate window.


hnumber

The highest tick price for this aggregate window.


lnumber

The lowest tick price for this aggregate window.


anumber

The tick's volume weighted average price.


zinteger

The average trade size for this aggregate window.


sinteger

The timestamp of the starting tick for this aggregate window in Unix Milliseconds.


einteger

The timestamp of the ending tick for this aggregate window in Unix Milliseconds.


Response Object

{
 "ev": "A",
 "sym": "SPCE",
 "v": 200,
 "av": 8642007,
 "op": 25.66,
 "vw": 25.3981,
 "o": 25.39,
 "c": 25.39,
 "h": 25.39,
 "l": 25.39,
 "a": 25.3714,
 "z": 50,
 "s": 1610144868000,
 "e": 1610144869000
}

Aggregates (Per Minute)

ws
Delayed:wss://delayed.polygon.io/stocks
Real-time:wss://socket.polygon.io/stocks

Stream real-time minute aggregates for a given stock ticker symbol.

Parameters

Specify a ticker symbol or use * to retreive all tickers. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"AM.{ticker}"}

Response Attributes
evenum [AM]

The event type.


symstring

The ticker symbol for the given stock.


vinteger

The tick volume.


avinteger

Today's accumulated volume.


opnumber

Today's official opening price.


vwnumber

Today's volume weighted average price.


onumber

The opening tick price for this aggregate window.


cnumber

The closing tick price for this aggregate window.


hnumber

The highest tick price for this aggregate window.


lnumber

The lowest tick price for this aggregate window.


anumber

The tick's volume weighted average price.


zinteger

The average trade size for this aggregate window.


sinteger

The timestamp of the starting tick for this aggregate window in Unix Milliseconds.


einteger

The timestamp of the ending tick for this aggregate window in Unix Milliseconds.


Response Object

{
 "ev": "AM",
 "sym": "GTE",
 "v": 4110,
 "av": 9470157,
 "op": 0.4372,
 "vw": 0.4488,
 "o": 0.4488,
 "c": 0.4486,
 "h": 0.4489,
 "l": 0.4486,
 "a": 0.4352,
 "z": 685,
 "s": 1610144640000,
 "e": 1610144700000
}

Limit-Up Limit-Down (LULD)

ws
Real-time:wss://socket.polygon.io/stocks

Stream real-time LULD events for a given stock ticker symbol.

Parameters

Specify a ticker symbol or use * to retreive all tickers. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"LULD.{ticker}"}

Response Attributes
evenum [LULD]

The event type.


Tstring

The ticker symbol for the given stock.


hnumber

The high price.


lnumber

The low price.


zinteger

The tape. (1 = NYSE, 2 = AMEX, 3 = Nasdaq).


tinteger

The Timestamp in Unix MS.


qinteger

The sequence number.


Response Object

{
 "ev": "LULD",
 "T": "MSFT",
 "h": 218.96,
 "l": 198.11,
 "i": [
  21
 ],
 "z": 3,
 "t": 1601316752683746,
 "q": 290317
}

Imbalances

ws
Real-time:wss://socket.polygon.io/stocks

Stream real-time imbalance events for a given stock ticker symbol.

Parameters

Specify a ticker symbol or use * to retreive all tickers. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"NOI.{ticker}"}

Response Attributes
evenum [NOI]

The event type.


Tstring

The ticker symbol for the given stock.


tinteger

The Timestamp in Unix MS.


atinteger

The time that the auction is planned to take place in the format (hour x 100) + minutes in Eastern Standard Time, for example 930 would be 9:30 am EST, and 1600 would be 4:00 pm EST.


astring

The auction type. O - Early Opening Auction (non-NYSE only) M - Core Opening Auction H - Reopening Auction (Halt Resume) C - Closing Auction P - Extreme Closing Imbalance (NYSE only) R - Regulatory Closing Imbalance (NYSE only)


iinteger

The symbol sequence.


xinteger

The exchange ID. See Exchanges for Polygon.io's mapping of exchange IDs.


ointeger

The imbalance quantity.


pinteger

The paired quantity.


bnumber

The book clearing price.


Response Object

{
 "ev": "NOI",
 "T": "NTEST.Q",
 "t": 1601318039223013600,
 "at": 930,
 "a": "M",
 "i": 44,
 "x": 10,
 "o": 480,
 "p": 440,
 "b": 25.03
}

Quotes

ws
Real-time:wss://socket.polygon.io/forex

Stream real-time forex quotes for a given forex pair.

Parameters

Specify a forex pair in the format {from}/{to} or use * to retreive all forex pairs. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"C.{ticker}"}

Response Attributes
evenum [C]

The event type.


pstring

The current pair.


xinteger

The exchange ID. See Exchanges for Polygon.io's mapping of exchange IDs.


anumber

The ask price.


bnumber

The bid price.


tinteger

The Timestamp in Unix MS.


Response Object

{
 "ev": "C",
 "p": "USD/CNH",
 "x": "44",
 "a": 6.83366,
 "b": 6.83363,
 "t": 1536036818784
}

Aggregates (Per Minute)

ws
Real-time:wss://socket.polygon.io/forex

Stream real-time per-minute forex aggregates for a given forex pair.

Parameters

Specify a forex pair in the format {from}/{to} or use * to retreive all forex pairs. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"CA.{ticker}"}

Response Attributes
evenum [CA]

The event type.


pairstring

The currency pair.


onumber

The open price for this aggregate window.


cnumber

The close price for this aggregate window.


hnumber

The high price for this aggregate window.


lnumber

The low price for this aggregate window.


vinteger

The volume of trades during this aggregate window.


sinteger

The start time for this aggregate window in Unix Milliseconds.


einteger

The end time for this aggregate window in Unix Milliseconds.


Response Object

{
 "ev": "CA",
 "pair": "USD/EUR",
 "o": 0.8687,
 "c": 0.86889,
 "h": 0.86889,
 "l": 0.8686,
 "v": 20,
 "s": 1539145740000
}

Trades

ws
Real-time:wss://socket.polygon.io/crypto

Stream real-time crypto trades for a given crypto pair.

Parameters

Specify a crypto pair in the format {from}-{to} or use * to retreive all crypto pairs. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"XT.{ticker}"}

Response Attributes
evenum [XT]

The event type.


pairstring

The crypto pair.


pnumber

The price.


tinteger

The Timestamp in Unix MS.


snumber

The size.


carray [integer]

The conditions. 0 (or empty array): empty 1: sellside 2: buyside


iinteger

The ID of the trade (optional).


xinteger

The crypto exchange ID. See Crypto Exchanges for a list of exchanges and their IDs.


rinteger

The timestamp that the tick was recieved by Polygon.


Response Object

{
 "ev": "XT",
 "pair": "BTC-USD",
 "p": 33021.9,
 "t": 1610462007425,
 "s": 0.01616617,
 "c": [
  2
 ],
 "i": 14272084,
 "x": 3,
 "r": 1610462007576
}

Quotes

ws
Real-time:wss://socket.polygon.io/crypto

Stream real-time crypto quotes for a given crypto pair.

Parameters

Specify a crypto pair in the format {from}-{to} or use * to retreive all crypto pairs. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"XQ.{ticker}"}

Response Attributes
evenum [XQ]

The event type.


pairstring

The crypto pair.


bpnumber

The bid price.


bsnumber

The bid size.


apnumber

The ask price.


asnumber

The ask size.


tinteger

The Timestamp in Unix MS.


xinteger

The crypto exchange ID. See Crypto Exchanges for a list of exchanges and their IDs.


rinteger

The timestamp that the tick was recieved by Polygon.


Response Object

{
 "ev": "XQ",
 "pair": "BTC-USD",
 "bp": 33052.79,
 "bs": 0.48,
 "ap": 33073.19,
 "as": 0.601,
 "t": 1610462411115,
 "x": 1,
 "r": 1610462411128
}

Level 2 Book

ws
Real-time:wss://socket.polygon.io/crypto

Stream real-time level 2 book data for a given crypto pair.

Parameters

Specify a crypto pair in the format {from}-{to} or use * to retreive all crypto pairs. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"XL2.{ticker}"}

Response Attributes
evenum [XL2]

The event type.


pairstring

The crypto pair.


barray

An array of bid prices with a maximum depth of 100.

aarray

An array of ask prices with a maximum depth of 100.

tinteger

The Timestamp in Unix MS.


xinteger

The crypto exchange ID. See Crypto Exchanges for a list of exchanges and their IDs.


rinteger

The timestamp that the tick was recieved by Polygon.


Response Object

{
 "ev": "XL2",
 "pair": "BTC-USD",
 "t": 1610462411115,
 "r": 1610462411128,
 "x": 1,
 "b": [
  [
   33712.71,
   0.18635
  ],
  [
   33712.7,
   0.134
  ]
 ],
 "a": [
  [
   33718.23,
   3.5527483
  ],
  [
   33718.24,
   0.1
  ]
 ]
}

Aggregates (Per Minute)

ws
Real-time:wss://socket.polygon.io/crypto

Stream real-time per-minute crypto aggregates for a given crypto pair.

Parameters

Specify a crypto pair in the format {from}-{to} or use * to retreive all crypto pairs. You can also use a comma separated list to retrieve multiple tickers.

{"action":"subscribe", "params":"XA.{ticker}"}

Response Attributes
evenum [XA]

The event type.


pairstring

The crypto pair.


onumber

The open price for this aggregate window.


cnumber

The close price for this aggregate window.


hnumber

The high price for this aggregate window.


lnumber

The low price for this aggregate window.


vinteger

The volume of trades during this aggregate window.


sinteger

The start time for this aggregate window in Unix Milliseconds.


einteger

The end time for this aggregate window in Unix Milliseconds.


Response Object

{
 "ev": "XA",
 "pair": "BCD-USD",
 "v": 951.6112,
 "vw": 0.7756,
 "z": 73.33,
 "o": 0.772,
 "c": 0.784,
 "h": 0.784,
 "l": 0.771,
 "s": 1610463240000,
 "e": 1610463300000
}