Docs
Flowseeker/API Reference/Contract

Raw enriched trades for a contract

GEThttps://api.skylit.ai/v1/contract/{symbol}/trades

Same enriched trade shape as /v1/underlying/{ticker}/trades, scoped to a single OPRA contract. Because the contract is fixed, chain-level filters (moneyness, strike, DTE, expiration) do not apply here.

Paging. Trades come largest premium first. When a page is full, meta.nextCursor is set: pass it back as cursor with the same start, end and filters for the next page. No gaps or repeats; no nextCursor means the window is exhausted. Splitting the time window instead re-reads overlapping ranges and gets an X-Skylit-Hint response header.

Authorization

Authorization: Bearer <your API key>

Required. A missing header returns 401; an invalid, revoked or expired key returns 403.

Path parameters

  • symbolstringrequired

    OPRA option symbol in URL-safe form: {ticker}__{YYMMDD}{C|P}{strike×1000, 8 digits} — the ticker and the 15-character contract block are joined by a double underscore (__). For example, an AAPL $250 call expiring 2026-01-17 is AAPL__260117C00250000. (A space-padded 21-char OCC form such as AAPL 260117C00250000 is also accepted on some endpoints, but the __ form is canonical and works across all contract routes.)

Query parameters

  • cursorstring

    meta.nextCursor from the previous page, passed back unchanged with the same filters. Opaque; an invalid value returns 400.

  • startstring

    Lower time bound — RFC 3339 or Unix seconds. Defaults to start-of-trading-day.

  • endstring

    Upper time bound — RFC 3339 or Unix seconds. Defaults to now.

  • limitintegerdefault 50min 1 · max 500
  • only_sweepsboolean
  • only_multi_legboolean
  • exclude_multi_legboolean
  • min_premiumnumberdoublemin 0

Responses

  • 200

    Enriched trades for the contract.

  • 400

    Request validation failed.

  • 401

    Missing or invalid API key.

  • 402

    The account's shared Skylit credit balance is lower than this route's cost. Top up to continue. Carries X-Credits-Remaining: 0.

  • 403

    Unknown, revoked or expired API key (the gateway's forbidden), the account's API access is suspended (account_suspended) or blocked (account_blocked). Not retryable.

  • 404

    Unknown ticker or contract (SYMBOL_NOT_FOUND), or no data for the requested window. Not charged.

  • 429

    Either the key exceeded its requests-per-minute limit (X-RateLimit-Limit; no Retry-After, wait until X-RateLimit-Reset), or the account is over one of the API's own limits, such as the query budget (queries running at once, fresh queries per second): TOO_MANY_CONCURRENT_QUERIES or RATE_LIMITED with Retry-After. Not charged; retry after the wait.

  • 500

    Unexpected server error (INTERNAL_ERROR, DATABASE_ERROR). Not charged; safe to retry with exponential backoff.

  • 503

    Underlying data source temporarily unavailable, the credit balance could not be verified (credit_check_failed), or the API is paused for maintenance (api_paused, with a Retry-After header and a retry_after field in seconds). Not charged; safe to retry.

  • 504

    The request did not complete within 25 seconds. Not charged; narrow the window or retry.

Response fields

  • dataobject[]required
    • dateintegerrequired

      Days since 1970-01-01 (compact session date).

    • tsEventintegerint64required

      Trade event timestamp in milliseconds since epoch.

    • tsEventUsintegerint64

      Microsecond-precision timestamp (contract-trades endpoint only).

    • instrumentIdintegerint64required
    • rawSymbolstringrequired
    • tickerstringrequired
    • expirationintegerrequired

      Expiration as days since 1970-01-01.

    • strikenumberdoublerequired
    • rightstringrequired
      CP
    • dteintegerrequired
    • pricenumberdoublerequired
    • sizeintegerrequired
    • sidestringrequired

      Granular execution-side label — BB (below bid), B (bid), AB (above bid), M (mid), BA (below ask), A (ask), AA (above ask), or N (no BBO).

      BBBABMBAAAAN
    • publisherIdintegerrequired
    • bidPxnumber | nulldouble
    • askPxnumber | nulldouble
    • bidSzinteger | null
    • askSzinteger | null
    • neutralSzintegerrequired
    • totalPremiumnumberdoublerequired
    • spreadnumber | nulldouble
    • underlyingPricenumberdoublerequired
    • ivnumber | nulldouble
    • moneynessstringrequired
      ITMATMOTM
    • moneynessPercentnumberdoublerequired
    • openInterestintegerrequired
    • prevOiintegerrequired
    • prevClosenumber | nulldouble
    • prevCloseAgeinteger | null

      Trading days back the prevClose came from (0 = yesterday).

    • priceChangenumber | nulldouble
    • dailyVolumeintegerrequired
    • sweepTradebooleanrequired
    • blockTradebooleanrequired
    • multiLegbooleanrequired
    • crossTradebooleanrequired

      Pre-negotiated cross (OPRA condition 127): both sides were matched before the print, so side says nothing about who initiated it.

    • ivDirectionintegerrequired

      -1 = down, 0 = flat/unknown, 1 = up.

      -101
    • ingestionTimestampintegerint64required

      Server ingest time in milliseconds since epoch.

    • prevIvnumber | nulldouble
    • nextIvnumber | nulldouble
    • premiumPercentileinteger

      Bucketed premium percentile band (0 = below P50, 99 = P99+).

      05075909599
    • flowScoreinteger
    • chainBidPctnumberdouble
    • chainAskPctnumberdouble
    • contractBidPctnumberdouble
    • contractAskPctnumberdouble
    • aggCountinteger
    • aggTotalPremiumnumberdouble
    • aggTotalSizeinteger
    • mlSiblingboolean

      True when this leg was included via spread association rather than its own filter match.

    • strategyGroupIdstring
    • strategyTypestring
    • strategyLegCountinteger
    • earningsDteinteger
    • nextEarningsDateinteger | null
    • cacheMissboolean
    • sectorstring
    • industrystring
  • metaobjectrequired
    • timestampstringdate-timerequired

      Server-side timestamp the response was generated at.

    • requestIdstringrequired

      Short opaque ID for log correlation.

    • nextCursorstring

      Trade feeds (/v1/flow/{ticker}, /v1/contract/{symbol}/trades): pass back as cursor with the same filters for the next page. Present only when more rows may follow.

    • nextEndTimestringdate-time

      /v1/flow/{ticker} only: the last row's exact time (RFC 3339 with nanoseconds), for end_time paging. Inclusive, so rows at that instant can repeat; nextCursor never repeats or skips.

Last updated

Was this page helpful?