# Live SEC Filings

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

Subscribe to live SEC EDGAR filings over the same WebSocket connection. Use channel F.{ticker} for a specific ticker (e.g. F.AAPL) or F.* for every new filing market-wide. Each message is pushed the moment a filing is indexed and carries metadata only - ticker, company, CIK, form type, filed date, accession number, EDGAR base URL, and the Vantafin filing id. Fetch the full filing document and exhibits via REST /filings/by-id/{id}. Like news, filings stream around the clock.

## Use cases

- Real-time filing alerts for 8-K, 10-K, 10-Q and other form types
- Event-driven workflows when a watchlist company files with the SEC
- Compliance and research feeds without polling the REST filings API
- Triggering document retrieval pipelines as filings are published

## Subscribe

Subscribe to `F.{ticker}` (e.g. `F.AAPL`) for a single ticker, or `F.*` for every ticker:

```json
{"action":"subscribe","params":"F.AAPL"}
```

## Message fields

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Always 'filing'. |
| `ticker` | string | Ticker that filed. |
| `company` | string | Company or fund name. |
| `cik` | string | SEC Central Index Key. |
| `form` | string | SEC form type, e.g. 10-K, 10-Q, 8-K. |
| `date` | string | Filing timestamp (ISO 8601). |
| `accession` | string | SEC accession number. |
| `edgar_base` | string | Base URL for the filing on SEC EDGAR. |
| `id` | string | Vantafin filing id (same as REST /filings/by-id/{id}). |

## Example output

```json
{
  "type": "filing",
  "ticker": "AAPL",
  "company": "Apple Inc.",
  "cik": "0000320193",
  "form": "8-K",
  "date": "2026-06-16T14:30:00Z",
  "accession": "0000320193-26-000045",
  "edgar_base": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000045",
  "id": "0000320193_000032019326000045"
}
```

## Connection examples

### cURL

```bash
# install websocat: https://github.com/vi/websocat
echo '{"action":"subscribe","params":"F.AAPL"}' \
  | websocat "wss://socket.vantafin.com/v1/stocks?apiKey=$VANTAFIN_API_KEY"
```

### Python

```python
from vantafin import WebSocketClient

ws = WebSocketClient("vf-live-your_api_key")
ws.connect()
ws.subscribe(["F.AAPL"])

for message in ws:
    print(message)
```

### JavaScript

```javascript
import { WebSocketClient } from "vantafin";

const ws = new WebSocketClient("vf-live-your_api_key");
ws.on("message", (msg) => console.log(msg));

await ws.connect();
ws.subscribe(["F.AAPL"]);
```

### Go

```go
package main

import (
	"fmt"
	"log"

	"github.com/vantafin/vantafin-go"
)

func main() {
	ws := vantafin.NewWebSocketClient("vf-live-your_api_key")
	conn, err := ws.Connect()
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	conn.Subscribe("F.AAPL")
	for {
		msg, err := conn.Read()
		if err != nil {
			break
		}
		fmt.Println(msg)
	}
}
```

### Java

```java
import com.vantafin.WebSocketClient;

public class Example {
    public static void main(String[] args) throws Exception {
        WebSocketClient ws = new WebSocketClient("vf-live-your_api_key");
        ws.connect(message -> System.out.println(message));
        ws.subscribe("F.AAPL");
    }
}
```

### Ruby

```ruby
require "vantafin"

ws = Vantafin::WebSocketClient.new("vf-live-your_api_key")
ws.on(:message) { |msg| pp msg }
ws.connect
ws.subscribe("F.AAPL")
sleep
```