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 retrieve 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 retrieve 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. This represents the number of round lot orders at the given bid price. The normal round lot size is 100 shares. A bid size of 2 means there are 200 shares for purchase at the given bid price.
axinteger
The ask exchange ID.
apnumber
The ask price.
asinteger
The ask size. This represents the number of round lot orders at the given ask price. The normal round lot size is 100 shares. An ask size of 2 means there are 200 shares available to purchase at the given ask price.
cinteger
The condition.
tinteger
The Timestamp in Unix MS.
zinteger
The tape. (1 = NYSE, 2 = AMEX, 3 = Nasdaq).
Response Object
{
"ev": "Q",
"sym": "MSFT",
"bx": 4,
"bp": 114.125,
"bs": 100,
"ax": 7,
"ap": 114.128,
"as": 160,
"c": 0,
"t": 1536036818784,
"z": 3
}
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 retrieve 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 retrieve 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 retrieve 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.
iarray [integer]
The Indicators.
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 retrieve 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 retrieve 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 retrieve 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 retrieve 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 retrieve 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 retrieve 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 retrieve 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
}