spb/hfmarketdata

1asyncapi: 3.0.02info:3  title: HF Market Data — Filings stream4  version: 1.0.05  description: |6    WebSocket stream of SEC EDGAR filing events for the companies covered by `/v1/fundamentals`.7    One socket, one channel (`filings`), JSON text frames. Authentication by API key8    (`?api_key=<key>` or `Authorization: Bearer <key>`); keyless connections receive an `error`9    message and are closed with code **4001**. At most **5 concurrent connections per key** (6th →10    `STREAM_CONNECTION_LIMIT`, close **4029**). Heartbeat every **20 s**. The server keeps the last11    **1 000** events; `resume_token` (the last `seq` you received) replays what you missed.12    Each `filing` message delivered is charged **1 row** on your rows quota (reduced rate).13  contact:14    name: Simon-Pierre Boucher15    email: contact@spboucher.ai16    url: https://www.hfmarketdata.io17  license:18    name: Data: SEC EDGAR (public domain) — see terms19    url: https://www.hfmarketdata.io/docs/terms20defaultContentType: application/json2122servers:23  production:24    host: www.hfmarketdata.io25    pathname: /v1/stream26    protocol: wss27    description: Production WebSocket endpoint.28    security:29      - $ref: '#/components/securitySchemes/apiKeyQuery'30      - $ref: '#/components/securitySchemes/apiKeyBearer'3132channels:33  stream:34    address: /v1/stream35    title: Single multiplexed socket36    description: |37      All messages flow on the one socket. Client → server: `subscribe`, `unsubscribe`, `ping`.38      Server → client: `hello`, `subscribed`, `unsubscribed`, `filing`, `heartbeat`, `pong`, `error`.39    messages:40      subscribe:41        $ref: '#/components/messages/subscribe'42      unsubscribe:43        $ref: '#/components/messages/unsubscribe'44      ping:45        $ref: '#/components/messages/ping'46      hello:47        $ref: '#/components/messages/hello'48      subscribed:49        $ref: '#/components/messages/subscribed'50      unsubscribed:51        $ref: '#/components/messages/unsubscribed'52      filing:53        $ref: '#/components/messages/filing'54      heartbeat:55        $ref: '#/components/messages/heartbeat'56      pong:57        $ref: '#/components/messages/pong'58      error:59        $ref: '#/components/messages/error'6061operations:62  subscribeFilings:63    action: send64    channel:65      $ref: '#/channels/stream'66    summary: Subscribe to the `filings` channel (optionally filtered by tickers / forms, resumable).67    messages:68      - $ref: '#/channels/stream/messages/subscribe'69    reply:70      channel:71        $ref: '#/channels/stream'72      messages:73        - $ref: '#/channels/stream/messages/subscribed'74        - $ref: '#/channels/stream/messages/error'75  unsubscribe:76    action: send77    channel:78      $ref: '#/channels/stream'79    messages:80      - $ref: '#/channels/stream/messages/unsubscribe'81  ping:82    action: send83    channel:84      $ref: '#/channels/stream'85    messages:86      - $ref: '#/channels/stream/messages/ping'87    reply:88      channel:89        $ref: '#/channels/stream'90      messages:91        - $ref: '#/channels/stream/messages/pong'92  receiveEvents:93    action: receive94    channel:95      $ref: '#/channels/stream'96    summary: Server pushes — the first frame is always `hello`.97    messages:98      - $ref: '#/channels/stream/messages/hello'99      - $ref: '#/channels/stream/messages/filing'100      - $ref: '#/channels/stream/messages/heartbeat'101      - $ref: '#/channels/stream/messages/error'102103components:104  securitySchemes:105    apiKeyQuery:106      type: httpApiKey107      name: api_key108      in: query109      description: '`wss://www.hfmarketdata.io/v1/stream?api_key=hfmd_live_…`'110    apiKeyBearer:111      type: http112      scheme: bearer113      bearerFormat: hfmd_live_…114      description: '`Authorization: Bearer hfmd_live_…` on the upgrade request.'115116  messages:117    subscribe:118      name: subscribe119      title: Subscribe120      summary: Start (or replace) the subscription of this socket.121      payload:122        type: object123        required: [action]124        properties:125          action:126            const: subscribe127          channel:128            type: string129            enum: [filings]130            default: filings131          tickers:132            description: List of tickers (any share class) or the string `"all"`.133            oneOf:134              - type: array135                minItems: 1136                items: { type: string }137              - const: all138            default: all139          forms:140            description: Form types to receive; omitted = all (10-K, 10-Q, 8-K, 20-F, 40-F, 6-K and amendments).141            type: array142            items: { type: string, examples: ['10-K', '10-Q', '8-K', '20-F', '10-K/A'] }143          resume_token:144            description: Last `seq` received; events with a greater `seq` still in the 1 000-event buffer are replayed first.145            type: integer146      examples:147        - name: Apple and Microsoft periodic reports, resumed148          payload: { action: subscribe, channel: filings, tickers: [AAPL, MSFT], forms: ['10-K', '10-Q'], resume_token: 1287 }149    unsubscribe:150      name: unsubscribe151      payload:152        type: object153        properties:154          action: { const: unsubscribe }155    ping:156      name: ping157      payload:158        type: object159        properties:160          action: { const: ping }161    hello:162      name: hello163      summary: First server frame after authentication.164      payload:165        type: object166        required: [type, seq, heartbeat_seconds]167        properties:168          type: { const: hello }169          seq: { type: integer, description: Current last sequence number (use it later as `resume_token`). }170          heartbeat_seconds: { type: number, const: 20 }171          max_connections_per_key: { type: integer, const: 5 }172          buffer: { type: integer, const: 1000 }173          ts: { type: string, format: date-time }174    subscribed:175      name: subscribed176      payload:177        type: object178        properties:179          type: { const: subscribed }180          channel: { const: filings }181          tickers:182            oneOf: [{ type: array, items: { type: string } }, { const: all }]183          forms:184            oneOf: [{ type: array, items: { type: string } }, { const: all }]185          resume_from: { type: integer }186          ts: { type: string, format: date-time }187    unsubscribed:188      name: unsubscribed189      payload:190        type: object191        properties:192          type: { const: unsubscribed }193          ts: { type: string, format: date-time }194    filing:195      name: filing196      title: Filing event197      summary: A new EDGAR filing of a covered company (published by the ingestion within ~2 minutes of EDGAR acceptance).198      payload:199        type: object200        required: [type, ticker, cik, form, filed_date, url, accn, seq]201        properties:202          type: { const: filing }203          ticker: { type: string, examples: [AAPL] }204          cik: { type: integer, examples: [320193] }205          form: { type: string, examples: ['10-Q'] }206          period: { type: [string, 'null'], format: date, description: Period of report. }207          filed_date: { type: string, format: date }208          url: { type: string, format: uri, description: Primary document on EDGAR. }209          accn: { type: string, description: Accession number. }210          seq: { type: integer, description: Monotonic sequence number (resume token). }211          summary:212            description: Standardized figures of the filing's own period (null for 8-K and when not yet normalized). Raw USD.213            type: [object, 'null']214            properties:215              revenue: { type: [number, 'null'] }216              net_income: { type: [number, 'null'] }217              eps_diluted: { type: [number, 'null'] }218              total_assets: { type: [number, 'null'] }219              operating_cash_flow: { type: [number, 'null'] }220              fiscal_year: { type: integer }221              fiscal_quarter: { type: integer, description: 1–4, 0 = fiscal year }222              yoy:223                type: object224                description: Year-over-year growth versus the same fiscal period one year earlier (null when the base is missing or ≤ 0).225                properties:226                  revenue: { type: [number, 'null'] }227                  net_income: { type: [number, 'null'] }228                  eps_diluted: { type: [number, 'null'] }229      examples:230        - name: Apple 10-Q for the quarter ended 2024-03-30231          payload:232            type: filing233            ticker: AAPL234            cik: 320193235            form: 10-Q236            period: '2024-03-30'237            filed_date: '2024-05-03'238            url: https://www.sec.gov/Archives/edgar/data/320193/000032019324000069/aapl-20240330.htm239            accn: 0000320193-24-000069240            seq: 1288241            summary:242              revenue: 90753000000243              net_income: 23636000000244              eps_diluted: 1.53245              total_assets: 337411000000246              operating_cash_flow: 22690000000247              fiscal_year: 2024248              fiscal_quarter: 2249              yoy: { revenue: -0.0431, net_income: -0.0222, eps_diluted: 0.0066 }250    heartbeat:251      name: heartbeat252      summary: Sent every 20 s while the socket is open.253      payload:254        type: object255        properties:256          type: { const: heartbeat }257          ts: { type: string, format: date-time }258          seq: { type: integer }259    pong:260      name: pong261      payload:262        type: object263        properties:264          type: { const: pong }265          ts: { type: string, format: date-time }266          seq: { type: integer }267    error:268      name: error269      summary: Same envelope fields as the REST errors (`code`, `message`, `docs`). Fatal errors are followed by a close frame.270      payload:271        type: object272        required: [type, code, message, docs]273        properties:274          type: { const: error }275          code:276            type: string277            enum: [AUTH_REQUIRED, STREAM_CONNECTION_LIMIT, VALIDATION_ERROR, NOT_FOUND]278          message: { type: string }279          docs: { type: string, format: uri }280          limit: { type: integer, description: Present on STREAM_CONNECTION_LIMIT. }281      examples:282        - name: keyless connection (then close 4001)283          payload:284            type: error285            code: AUTH_REQUIRED286            message: 'A valid API key is required for the stream: pass ?api_key=… or Authorization: Bearer ….'287            docs: https://www.hfmarketdata.io/docs/errors#auth_required288289x-close-codes:290  '4001': AUTH_REQUIRED — no or invalid API key291  '4029': STREAM_CONNECTION_LIMIT — more than 5 concurrent sockets for this key292  '4400': protocol error293