Client Update Needed To Match WebSocket Spec Changes
Overview
A diff between the client library's spec and our hosted spec was found, indicating that the client may need an update to match any changes in our API. This article will provide an overview of the changes and the necessary steps to update the client library.
Changes in the WebSocket Spec
The WebSocket spec has undergone changes, which are reflected in the diff provided below. The changes include the addition of new endpoints, parameters, and responses.
--- https://raw.githubusercontent.com/polygon-io/client-go/master/.polygon/websocket.json
+++ https://api.polygon.io/specs/websocket.json
@@ -208,6 +208,30 @@
]
}
]
+ },
+ "futures": {
+ "market": [
+ {
+ "paths": [
+ "/futures/AM"
+ ]
+ },
+ {
+ "paths": [
+ "/futures/A"
+ ]
+ },
+ {
+ "paths": [
+ "/futures/T"
+ ]
+ },
+ {
+ "paths": [
+ "/futures/Q"
+ ]
+ }
+ ]
}
},
"paths": {
@@ -269,7 +293,7 @@
},
"c": {
"type": "array",
- "description": "The trade conditions. See <a target=\"_blank\" href=\"https://polygon.io/glossary/us/stocks/conditions-indicators\" \nalt=\"Conditions and Indicators\">Conditions and Indicators\"</a> for Polygon.io's trade conditions glossary.\n",
+ "description": "The trade conditions. See <a target=\"_blank\" href=\"https://polygon.io/glossary/us/stocks/conditions-indicators\" \nalt=\"Conditions and Indicators\">Conditions and Indicators</a> for Polygon.io's trade conditions glossary.\n",
"items": {
"type": "integer",
"description": "The ID of the condition."
@@ -277,7 +301,7 @@
},
"t": {
"type": "integer",
- "description": "The Timestamp in Unix MS."
+ "description": "The SIP timestamp in Unix MS."
},
"q": {
"type": "integer",
@@ -407,7 +431,7 @@
},
"t": {
"type": "integer",
- "description": "The Timestamp in Unix MS."
+ "description": "The SIP timestamp in Unix MS."
},
"q": {
"type": "integer",
@@ -3694,6 +3718,490 @@
}
]
}
+ },
+ "/futures/T": {
+ "get": {
+ "summary": "Trades",
+ "description": "Stream real-time trades for a given future ticker symbol.\n",
+ "parameters": [
+ {
+ "name": "ticker",
+ "in": "query",
+ "description": "Specify a future ticker or use * to subscribe to all future tickers.\nYou can also use a comma separated list to subscribe to multiple future tickers.\nYou can retrieve available future tickers from our [Futures Tickers API](https://polygon.io/docs/futures/get_v3_reference_tickers).\n",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "pattern": "/^([a-zA-Z]+)$/"
+ },
+ "example": "*"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The WebSocket message for a trade event.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "ev": {
+ "enum": [
+ "T"
+ ],
+ "description": "The event type."
+ },
+ "sym": {
+ "type": "string",
+ "description": "The ticker symbol for the given future."
+ },
+ "p": {
+ "type": "number",
+ "format": "double",
+ "description": "The price of a trade."
+ },
+ "s": {
+ "type": "integer",
+ "description": "The trade size."
+ },
+ "t": {
+ "type": "integer",
+ "description": "The SIP timestamp in Unix MS."
+ },
+ "q": {
+ "type": "integer",
+ "description": "The sequence number represents the sequence in which message events happened.\nThese are increasing and unique per ticker symbol, but will not always be\nsequential (e.g., 1, 2, 6, 9, 10, 11).\n"
+ }
+ }
+ },
+ "example": {
+ "ev": "T",
+ "sym": "ESZ4",
+ "z": 3,
+ "p": 606450,
+ "s": 100,
+ "t": 1734103628363,
+ "q": 32599300
+ }
+ }
+ }
+ }
+ },
+ "x-polygon-entitlement-data-type": {
+ "name": "trades",
+ "description": "Trade data"
+ },
+ "x-polygon-entitlement-market-type": {
+ "name": "futures",
+ "description": "Futures data"
+ },
+ "x-polygon-entitlement-allowed-timeframes": [
+ {
+ "name": "futuresdelayed",
+ "description": "10 minute delayed data"
+ },
+ {
+ "name": "realtime",
+ "description": "Real Time Data"
+ }
+ ]
+ }
+ },
+ "/futures/Q": {
+ "get": {
+ "summary": "Quotes",
+ "description": "Stream real-time quotes for a given future ticker symbol.\n",
+ "parameters": [
+ {
+ "name": "ticker",
+ "in": "query",
+ "description": "Specify a future ticker or use * to subscribe to all future tickers.\nYou can also use a comma separated list to subscribe to multiple future tickers.\nYou can retrieve available future tickers from our [Futures Tickers API](https://polygon.io/docs/futures/get_v3_reference_tickers).\n",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "pattern": "/^([a-zA-Z]+)$/"
+ },
+ "example": "*"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The WebSocket message for a quote event.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "ev": {
+ "enum": [
+ "Q"
+ ],
+ "description": "The event type."
+ },
+ "sym": {
+ "type": "string",
+ "description": "The ticker symbol for the given future."
+ },
+ "bp": {
+ "type": "number",
+ "format": "double",
+ "description": "The bid price."
+ },
+ "bs": {
+ "type": "integer",
+ "description": "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."
+ },
+ "bt": {
+ "type": "integer",
+ "description": "The timestamp when the bid was submitted to the exchange."
+ },
+ "ap": {
+ "type": "number",
+ "format": "double",
+ "description": "The ask price."
+ },
+ "as": {
+ "type": "integer",
+ "description": "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."
+ },
+ "at": {
+ "type": "integer",
+ "description": "The timestamp when the ask was submitted to the exchange."
+ },
+ "t": {
+ "type": "integer",
+ "description": "The SIP timestamp in Unix MS."
+ }
+ }
+ },
+ "example": {
+ "ev": "Q",
+ "sym": "ESZ4",
+ "bx": 4,
+ "bp": 114.125,
+ "bs": 100,
+ "bt": 1734103628360,
+ "ap": 114.128,
+ "as": 160,
+ "at": 1734103628350,
+ "t": 1536036818784
+ }
+ }
+ }
+<br/>
**Client Update Needed to Match WebSocket Spec Changes: Q&A**
**Q: What is the purpose of this update?**
A: The purpose of this update is to ensure that the client library matches the latest changes in our WebSocket spec. This will ensure that the client can properly communicate with our API and receive the latest data.
**Q: What changes were made to the WebSocket spec?**
A: The changes include the addition of new endpoints, parameters, and responses. Specifically, new endpoints for trades, quotes, and aggregates were added, as well as new parameters and responses for these endpoints.
**Q: What are the new endpoints that were added?**
A: The new endpoints that were added are:
* `/futures/T`: This endpoint streams real-time trades for a given future ticker symbol.
* `/futures/Q`: This endpoint streams real-time quotes for a given future ticker symbol.
* `/futures/A`: This endpoint streams real-time aggregates for a given future ticker symbol.
* `/futures/AM`: This endpoint streams real-time minute aggregates for a given future ticker symbol.
**Q: What are the new parameters that were added?**
A: The new parameters that were added are:
* `ticker`: This parameter specifies the future ticker symbol to subscribe to. It can be a single ticker symbol or a comma-separated list of ticker symbols.
* `paths`: This parameter specifies the paths to subscribe to. It can be a single path or a comma-separated list of paths.
**Q: What are the new responses that were added?**
A: The new responses that were added are:
* `ev`: This response indicates the event type. It can be one of the following values: `T` for trades, `Q` for quotes, or `A` for aggregates.
* `sym`: This response indicates the ticker symbol of the event.
* `p`: This response indicates the price of the trade.
* `s`: This response indicates the size of the trade.
* `t`: This response indicates the timestamp of the event in Unix MS.
* `q`: This response indicates the sequence number of the event.
**Q: How do I update my client library to match the latest changes?**
A: To update your client library, you will need to modify the code to match the new endpoints, parameters, and responses. You can do this by:
* Updating the code to use the new endpoints.
* Updating the code to use the new parameters.
* Updating the code to handle the new responses.
**Q: What are the benefits of updating my client library?**
A: The benefits of updating your client library include:
* Ensuring that your client can properly communicate with our API.
* Ensuring that your client can receive the latest data.
* Improving the performance and reliability of your client.
**Q: What are the potential risks of not updating my client library?**
A: The potential risks of not updating your client library include:
* Your client may not be able to properly communicate with our API.
* Your client may not be able to receive the latest data.
* Your client may experience performance and reliability issues.
**Q: How can I get help with updating my client library?**
A: You can get help with updating your client library by:
* Contacting our support team.
* Checking our documentation and API reference.
* Joining our community forums and asking for help.