# WebSocket API

Real-time market data over a single socket. Connect, authenticate with your API key, and subscribe to channels for per-second and per-minute quotes, live news, SEC filings, and trading halts.

## Endpoint

`wss://socket.vantafin.com/v1/stocks`

## Authentication & subscribe

Send your API key on connect, then subscribe with `CODE.TICKER` selectors (e.g. `LS.AAPL`) or `CODE.*` for all tickers. Quote streams run 4:00 AM-8:00 PM ET on trading days; news and filings stream around the clock.

## Quick start

```python
import json
from websocket import create_connection

ws = create_connection("wss://socket.vantafin.com/v1/stocks")
ws.send(json.dumps({"action": "auth", "apiKey": "vf-live-your_api_key"}))
ws.send(json.dumps({"action": "subscribe", "channels": ["LS.AAPL"]}))

while True:
    print(ws.recv())
```

## Available streams

- **Live Quotes (Per Second)** - Per-second live quotes for the tickers you subscribe to. One message per ticker per second during market hours (4:00 AM-8:00 PM ET on trading days). Subscribe to the LS channel, e.g. LS.AAPL, or LS.* for every live ticker. If you subscribe while the market is closed - weekends, holidays, or after an early close - the socket replies with a market_status message instead of data. See /app/docs/websocket/live-quotes-per-second.
- **Live Quotes (Per Minute)** - Per-minute live quotes for the tickers you subscribe to. One message per ticker per minute during market hours (4:00 AM-8:00 PM ET on trading days). Subscribe to the LM channel, e.g. LM.AAPL, or LM.* for every live ticker. If you subscribe while the market is closed - weekends, holidays, or after an early close - the socket replies with a market_status message instead of data. See /app/docs/websocket/live-quotes-per-minute.
- **Live News** - Live news articles and press releases pushed the moment they are ingested. A message is delivered whenever a new article is published for a ticker you subscribe to. Subscribe to N.{ticker} for a specific ticker or N.* for every article market-wide. Each message carries a newsType field of either 'stockNews' or 'pressRelease'. Unlike the live-quote channels, news streams around the clock - it is not gated to market hours. See /app/docs/websocket/live-news.
- **Live SEC Filings** - Live SEC EDGAR filings pushed the moment they are ingested for a tracked ticker. A message is delivered whenever a new filing is indexed for a ticker you subscribe to. Subscribe to F.{ticker} for a specific ticker or F.* for every filing market-wide. Each message carries filing metadata only (form type, filed date, accession, EDGAR URL, etc.) - use the REST /filings endpoints for the full document and exhibits. Streams around the clock, like news. See /app/docs/websocket/live-sec-filings.
- **Trading Halts** - Trading halt and resumption events sourced from the official NASDAQ trade-halt feed. A message is pushed whenever a subscribed ticker's halt status changes. Subscribe to H.{ticker} for a specific ticker or H.* for every halt market-wide. See /app/docs/websocket/trading-halts.