API Documentation

Authentication

Pass your API key in the Authorization header:

curl https://voledge.io/api/v1/scanner \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/v1/scanner

Returns IV rank data for optionable stocks.

Query Parameters

GET /api/v1/scanner?minIVRank=80&sort=ivRank&order=desc&limit=10

GET /api/v1/flow

Returns unusual options flow and large orders.

Query Parameters

GET /api/v1/earnings

Returns upcoming earnings with IV crush analysis.

Query Parameters

Response Example

{
  "data": [
    {
      "symbol": "GME",
      "name": "GameStop",
      "currentIV": 145.2,
      "ivRank": 92,
      "ivPercentile": 95,
      "historicalVol": 78.5,
      "ivHvSpread": 66.7,
      "price": 24.85,
      "change": 5.2,
      "volume": 485000,
      "openInterest": 1250000,
      "putCallRatio": 0.65,
      "sector": "Consumer Discretionary"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

Response Example

{
  "data": [
    {
      "id": "1",
      "timestamp": "14:32:15",
      "symbol": "NVDA",
      "type": "call",
      "strike": 900,
      "expiry": "Mar 21",
      "premium": 2450000,
      "volume": 5200,
      "openInterest": 12500,
      "side": "buy",
      "sentiment": "bullish",
      "unusual": true
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

Response Example

{
  "data": [
    {
      "symbol": "NVDA",
      "name": "NVIDIA",
      "earningsDate": "2026-02-26",
      "daysUntil": 4,
      "currentIV": 55.8,
      "avgPreEarningsIV": 62.5,
      "avgPostEarningsIV": 38.2,
      "avgIVCrush": 38.9,
      "estimatedMove": 8.5,
      "historicalMoves": [16.4, -7.6, 24.4, -2.5]
    }
  ],
  "meta": { "total": 1 }
}

GET /api/v1/watchlist

Returns the authenticated user's watchlist with current market data.

{
  "items": [
    {
      "symbol": "NVDA",
      "name": "NVIDIA",
      "ivRank": 65,
      "currentIV": 55.8,
      "price": 875.20,
      "change": 2.1,
      "alertThreshold": 80
    }
  ]
}

POST /api/v1/watchlist

Adds a symbol to the authenticated user's watchlist.

Request Body

// Request
POST /api/v1/watchlist
{ "symbol": "AAPL", "alertThreshold": 75 }

// Response (201)
{
  "item": {
    "symbol": "AAPL",
    "name": "Apple",
    "ivRank": 35,
    "currentIV": 22.5,
    "price": 192.50,
    "change": -0.3,
    "alertThreshold": 75
  }
}

DELETE /api/v1/watchlist

Removes a symbol from the authenticated user's watchlist.

Query Parameters

DELETE /api/v1/watchlist?symbol=AAPL

// Response (200)
{ "success": true }

Error Responses

All endpoints return errors in a consistent format.

{ "error": "Description of the error" }

Common Status Codes

Rate Limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.