Pro API Documentation

Programmatic access to OptionWhales intent flow, momentum rankings, and abnormal trade detection.

Quick Start

Get your API key

Go to your Account page and generate a new API key. Keep it safe — it's shown only once.

Make your first request

Include your key in the X-API-Key header.

bash

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.optionwhales.io/v1/flow/current

Explore endpoints below

Free keys get limited data. Upgrade to Pro for full access including WebSocket streaming.

Authentication

All API requests require an API key passed via the X-API-Key header or as a ?api_key= query parameter.

bash

# Header (recommended)
curl -H "X-API-Key: ow_pro_abc123..." https://api.optionwhales.io/v1/flow/current

# Query parameter
curl "https://api.optionwhales.io/v1/flow/current?api_key=ow_pro_abc123..."

Never share your API key or commit it to source control. Use environment variables.

Rate Limits

Tier	Per Minute	Per Day	WebSocket
Free	10	200	Not available
Pro	60	5,000	1 connection

Rate limit headers are included in every response:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000060

When rate-limited, you receive a 429 Too Many Requests with a Retry-After header.

Free vs Pro

Feature	Free	Pro
Flow rankings	Top 3 tickers, limited fields	All tickers, all fields
Flow sessions list	Blocked	Full access
Ticker detail	Blocked	Full access
Momentum rankings	Top 3 tickers, limited fields	All tickers, all fields
Momentum history	Blocked	Multi-session
Abnormal trades	Last 5, limited fields	Full history, all fields
WebSocket streaming	Not available	Real-time stream

Endpoints

Intent Flow

Momentum

Abnormal Trades

Account

WebSocket Streaming

Pro keys only

Connect to the WebSocket endpoint for real-time abnormal trade detection. Trades are pushed to your connection as they are detected during market hours.

Connection URL

bash

wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key=YOUR_PRO_KEY

Filter by tickers (send after connecting)

json

{"type": "subscribe", "tickers": ["AAPL", "NVDA", "TSLA"]}

Python Example

python

import asyncio
import json
import websockets

API_KEY = "ow_pro_your_key_here"
URL = f"wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key={API_KEY}"

async def stream_trades():
    async with websockets.connect(URL) as ws:
        print("Connected! Waiting for trades...")
        async for message in ws:
            data = json.loads(message)
            if data.get("type") == "abnormal_trade":
                trade = data["data"]
                print(f"{trade['ticker']} {trade['side']} ${trade['premium']:,.0f}")
            elif data.get("type") == "heartbeat":
                print(".", end="", flush=True)

asyncio.run(stream_trades())

JavaScript Example

javascript

const API_KEY = "ow_pro_your_key_here";
const url = `wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key=${API_KEY}`;

const ws = new WebSocket(url);

ws.onopen = () => console.log("Connected!");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "abnormal_trade") {
    console.log(`${data.data.ticker} ${data.data.side} $${data.data.premium}`);
  }
};

ws.onerror = (err) => console.error("WebSocket error:", err);
ws.onclose = () => console.log("Disconnected");

Message Types

abnormal_trade

New abnormal trade detected. Contains full trade data in the data field.

heartbeat

Sent every 30 seconds to keep the connection alive. Contains ts timestamp.

subscribed

Confirmation after sending a subscribe message. Contains the active tickers filter list.

error

Error message. The connection may be closed after this.

Health Check

The health endpoint requires no authentication and returns the service status.

bash

curl https://api.optionwhales.io/health

json

{
  "status": "healthy",
  "service": "pro-api",
  "version": "1.0.0",
  "ws_connections": 0
}

Error Codes

Code	Description
`401`	Missing or invalid API key
`403`	Insufficient tier (endpoint requires Pro+)
`429`	Rate limit exceeded — check `Retry-After` header
`502`	Upstream data service unavailable

Ready to build?

Generate your API key and start integrating OptionWhales data into your trading workflow.

Get API Key Interactive Docs