Quickstart

The Polygon.io WebSocket API provides streaming market data from major US exchanges. To access this service, new users must sign up for a paid subscription plan and authenticate with an API key. While this guide illustrates the mechanics of how to manually connect, authenticate, and subscribe using command line tools, understanding these steps is crucial for grasping the underlying processes. However, for practical application, our client libraries streamline integration and are recommended for most users. These libraries are available in Python, Go, Kotlin, and JavaScript, and simplify the integration process with complete working code samples.

Initiate a Connection

To initiate a connection using your command line terminal, use the following command, which will automatically install wscat if it is not already installed.

• Delayed Access: For delayed data streams, connect with:

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

• Real-Time Access: For real-time data, connect using:

  npx wscat -c wss://socket.polygon.io/stocks
  

Upon successfully connecting, you will receive:

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

Note: By default only one WebSocket connection is allowed at a time. Please contact support if you require multiple simultaneous connections.

Authenticate Your Connection

Before accessing data, authenticate your connection by sending your API key:

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

Replace your_api_key_here with your actual API key. A successful authentication will confirm:

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

Subscribe to Data Feeds

Once authenticated, you can subscribe to the data feeds you need. Below is an example using the Stocks Aggregates (Per Minute), subscribing to the tickers AAPL and MSFT.

{"action":"subscribe", "params":"AM.AAPL, AM.MSFT"}

You can subscribe to multiple tickers in the same request to maximize efficiency.

Understand Message Formats

Messages from the WebSocket are formatted as JSON objects and may be bundled together in arrays to optimize delivery, especially during high-volume periods.

Example of a Single Event Message

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

Example of Multiple Event Messages in One Array

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

Manage Data and Reduce Latency

When using the WebSocket API, managing data volume and reducing latency are crucial for optimal performance:

• High-Volume Handling: WebSocket clients must process numerous messages per second. If your client is slow, the server buffers and regulates message flow, potentially leading to disconnection if the buffer overflows. To avoid this:

  • Ensure your client is capable of quick message processing.
  • Reduce subscription volume if disconnections occur frequently.

• Latency Reduction Recommendations:

  • Wired Connections: Use a hardwired connection rather than WiFi for more stable and faster data transmission.
  • Avoid VPNs: VPNs can introduce additional latency. If possible, connect directly to ensure the fastest response times.

If a client is consuming messages too slowly for an extended period, Polygon.io's server-side buffer may become too large. In such cases, we will terminate the WebSocket connection to maintain system integrity. You can check your account dashboard to see if a connection was terminated as a slow consumer. If this is a consistent issue, consider subscribing to fewer symbols or channels to manage the data flow more effectively.

Explore Client Libraries

To facilitate quick and effective integration, Polygon.io offers full-featured client libraries for Python, Go, Kotlin, and JavaScript. These libraries provide complete examples and are designed to help you get started quickly:

• Python: GitHub - Python Client
• Go: GitHub - Go Client
• Kotlin: GitHub - JVM Client
• JavaScript: GitHub - JavaScript Client

Utilize these libraries to streamline your development process and integrate Polygon.io's capabilities into your applications efficiently.

Next Steps

By following these steps and adhering to best practices, you can leverage the streaming capabilities of the Polygon.io WebSocket API. Ensure your setup is optimized for low latency and high-volume data handling to make the most of the streaming data services provided.