Alphanume Premarket Drop Risk API

openapi: 3.2.0
info:
  contact:
    url: https://alphanume.com
  description: 'Point-in-time, survivorship-aware datasets for US equities and options research. Every response is JSON: {"count": N, "data": [...]} (paginated endpoints add has_more and next_cursor). Dates are always YYYY-MM-DD. Access: every dataset requires an Alphanume Pro API key (the Free plan is retired as of September 6, 2026). A 403 error with code PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED means the key''s plan does not cover the request -- it does not mean the data is missing. Authentication: send your API key in the X-API-Key header (or Authorization: Bearer). Rate limit: 600 requests/minute. Keys come with a Pro subscription at https://alphanume.com/pricing. The same datasets are available as MCP tools at https://mcp.alphanume.com/mcp.'
  title: Alphanume Premarket Drop Risk API
  version: 1.1.0
servers:
- url: https://api.alphanume.com
security:
- ApiKeyHeader: []
- BearerKey: []
tags:
- name: Premarket Drop Risk
paths:
  /v1/premarket-drop-risk:
    get:
      description: 'Pre-market drop risk: model-estimated probability of an intraday decline in US microcaps, published each morning before the open.


        Each trading morning, by ~09:25 ET and ahead of the 09:30 open, a

        RandomForestClassifier scores every microcap that actually traded in the

        pre-market session and this dataset serves the names ranked by modeled drop

        risk. Features are cut at a fixed 09:00 ET pre-market cutoff. prob_drop is

        P(intraday open->close return <= -5%); one row per (date, ticker), ordered by

        rank_for_date (1 = the highest-probability name that day). It measures the

        subset the model flags, not everything that moved overnight, and is built for

        researchers and traders analyzing pre-market activity in US microcaps.


        Requires an Alphanume Pro API key. There is no date clamp on this route: a Pro

        key sees the whole history, whatever dates it asks for.


        Sub-$1 names are featured, not filtered. Every row the model flags is

        published, each carrying a sub_dollar flag: pass min_price=1 for the legacy

        ''$1 and up'' screen, sub_dollar=1 (or max_price=1) to isolate the penny

        cohort, max_rank=5 for the day''s top five.


        History before go-live (2026-08-31) is walk-forward simulated: generated

        retrospectively by re-running the walk-forward loop (train on strictly-prior

        rows only, then score that date). There is no look-ahead in the features or

        the training window, but rows dated before go-live are not a real-time

        publication record; rows from go-live onward are published live each morning

        before the open.


        Outcomes fill in late, never early. intraday_return_pct lands the same

        evening; return_lead_1d / return_lead_5d / return_lead_30d only once 1 / 5 /

        20 NYSE sessions have elapsed -- NULL means not yet mature, or no exchange

        print existed at maturity (halts and delistings, which this microcap universe

        produces regularly). Three documented quirks kept for continuity with the

        training set: return_lead_30d is 20 trading sessions rather than 30 calendar

        days; return_lag_1m uses the 21-session price change over the price 252

        sessions back (a legacy denominator quirk, so it is not a clean 1-month

        return); and the t_0..t_9 pre-market return grid is 0-filled, not NULL, when

        no print exists at or before that clock mark.


        Borrow and locate costs are NOT modeled. Shorting a sub-$1 microcap needs a

        locate that may be expensive or simply unavailable, and no number served

        here carries that cost. sub_dollar and min_price are the levers for filtering

        toward borrowable names.


        Pagination: results are capped at 50,000 rows per request; when the response

        has has_more=true, pass next_cursor''s date and rank_for_date back as

        cursor_date and cursor_rank to fetch the next page.'
      operationId: get_premarket_drop_risk
      parameters:
      - description: Ticker symbol filter, e.g. 'AAPL'. Case-insensitive.
        in: query
        name: ticker
        required: false
        schema:
          type: string
      - description: Exact date, YYYY-MM-DD. Cannot be combined with the date range parameters.
        in: query
        name: date
        required: false
        schema:
          type: string
      - description: Start of date range, inclusive (YYYY-MM-DD).
        in: query
        name: date_gte
        required: false
        schema:
          type: string
      - description: End of date range, inclusive (YYYY-MM-DD).
        in: query
        name: date_lte
        required: false
        schema:
          type: string
      - description: Start of date range, exclusive (YYYY-MM-DD).
        in: query
        name: date_gt
        required: false
        schema:
          type: string
      - description: End of date range, exclusive (YYYY-MM-DD).
        in: query
        name: date_lt
        required: false
        schema:
          type: string
      - description: Only rows with prob_drop >= this value, range [0, 1]. 0.7 keeps the model's higher-conviction names.
        in: query
        name: min_prob
        required: false
        schema:
          type: number
      - description: Only rows with px_at_trading >= this value (USD, >= 0). min_price=1 reproduces the legacy '$1 and up' screen.
        in: query
        name: min_price
        required: false
        schema:
          type: number
      - description: Only rows with px_at_trading <= this value (USD, >= 0). max_price=1 isolates the sub-$1 cohort. Must be >= min_price.
        in: query
        name: max_price
        required: false
        schema:
          type: number
      - description: '''1'' = only names priced under $1 at the 09:00 ET cutoff, ''0'' = only names at $1 or above. Convenience equivalent of min_price/max_price around $1.'
        in: query
        name: sub_dollar
        required: false
        schema:
          type: string
      - description: Only rows with rank_for_date <= this value (>= 1). max_rank=5 gives the top five names per day.
        in: query
        name: max_rank
        required: false
        schema:
          type: integer
      - description: 'Pagination: the ''date'' value from the previous response''s next_cursor. Must be sent together with cursor_rank.'
        in: query
        name: cursor_date
        required: false
        schema:
          type: string
      - description: 'Pagination: the ''rank_for_date'' value from the previous response''s next_cursor. Must be sent together with cursor_date.'
        in: query
        name: cursor_rank
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
          description: Matching rows.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProSubscriptionRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: 'Pre-market drop risk: model-estimated probability of an intraday decline in US…'
      tags:
      - Premarket Drop Risk
components:
  schemas:
    PaginatedEnvelope:
      properties:
        count:
          type: integer
        data:
          items:
            type: object
          type: array
        has_more:
          type: boolean
        next_cursor:
          description: 'Keyset cursor: pass its fields back as the cursor_* query parameters to fetch the next page.'
          type:
          - object
          - 'null'
      required:
      - count
      - data
      - has_more
      - next_cursor
      type: object
    Error:
      additionalProperties: true
      properties:
        error: {}
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or unrecognized API key.
    ProSubscriptionRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: 'PRO_SUBSCRIPTION_REQUIRED: the key''s plan does not include API access (every endpoint requires an active Pro subscription), or this Pro-only dataset is not covered by the key. No choice of dates makes the request succeed. The data is not missing.'
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Invalid or conflicting query parameters.
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Rate limit exceeded (600/min); the body carries retry_after_seconds.
  securitySchemes:
    ApiKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    BearerKey:
      scheme: bearer
      type: http
externalDocs:
  description: MCP server exposing these datasets as tools (OAuth or X-API-Key).
  url: https://mcp.alphanume.com/mcp