Helious Economic data API

openapi: 3.2.0
info:
  title: Helious Public Economic data API
  version: '2026-11-06'
  summary: Real-time US economic releases, Treasury auction results, rates and market news from the Helious desk.
  description: 'Read-only surface of api.helious.io. Every dataset here is first-party: captured by the Helious desk the moment it prints, with methodology at https://helious.io/methodology. On /v1/feed and the stream the Helious news wire rides beside the desk''s own posts: a wire headline is marked kind: headline and scored like everything else. The /v1 endpoints are the versioned contract for agents, and every tier sees the same endpoints and the same response shapes: only the history window, the delay and the market-data axis change, so an integration built keyless survives every upgrade untouched. The ladder: Sample (no key, no account, $0) gets 1 day of history, news and prints 1 hour behind, no market prices at all (price endpoints answer with the upgrade steps instead of numbers) and 30 calls a minute and 50 credits a month, shared by everyone on your network address. Free (a key on a free helious.io account, $0) gets 7 days of history, news 1 hour behind, every price board 60 minutes behind, and 60 calls a minute and 100 credits a month of your own. ONE CREDIT WALLET pays for everything an account does: a data call on any /v1 endpoint or MCP tool is 1 credit, a typed Ask Helious question in the terminal is 10, and on Free, Squawk and Starter the query fresh=1 (fresh: true as an MCP tool argument) answers that one call live for 5 credits. /v1/me, /v1/access, the MCP handshake, get_access_info, list_series, every error and every refusal are free; a keyless market wall is free too. Every answer carries X-Credits-Charged and X-Credits-Remaining headers and the same two numbers in meta (credits_charged, credits_left), and an empty wallet is a 429 with code out_of_credits carrying credits_left, resets_on, next_step (one sentence to relay), the packs that top it up (500 for $9.99, 1,500 for $24.99, never expiring) and upgrade_url: two ways on, a pack or a plan, and the person who owns the key chooses. Not on Pro and need one call live? Add fresh=1 to that request (fresh: true in an MCP tool''s arguments) and it answers live for 5 credits. Each delayed stream snapshot takes one credit on Free and with no key; a paid plan''s stream takes none. Starter ($14.99/mo or $135/yr) gets 12 months of history, live news and prints, every price board 60 minutes behind (live for 5 credits a call with fresh=1), 1,500 credits a month, at 90 calls a minute. Pro ($39.99/mo or $360/yr) gets 24 months of history, 3,000 credits a month and everything live for 1 credit (yields, treasuries, commodities, equities, FX, volatility, correlations) at 120 calls a minute, the streaming WebSocket included. Ultimate ($99/mo or $891/yr) gets 10 years of history, everything live, no credit cap, commercial use and redistribution, 300 calls a minute and the live stream on 5 connections a key. The stream at wss://api.helious.io/v1/stream is open on every tier, key or no key: below Pro it runs the delayed lane (one snapshot a minute, prices and the ranked NASDAQ-100 board 60 minutes behind, news on the plan''s own delay), and Pro and Ultimate run the live lane (every price tick, print and NASDAQ-100 update pushed the moment it happens, on up to 2 connections a key on Pro and 5 on Ultimate), in identical message shapes, so a stream integration survives the upgrade untouched. Authenticate with the same hel_ key sent as the ''Authorization: Bearer hel_...'' header, never a query parameter; the socket sends a hello whose mode field names your lane, feed items in the /v1/feed shape, price ticks, the ranked NASDAQ-100 board, daily official closes and the Helious momentum score, and answers ''ping'' with pong. Keys are sent as ''Authorization: Bearer hel_...''; GET /v1/access returns the ladder and the exact upgrade steps in plain words. There is also an MCP server at https://api.helious.io/mcp: point any MCP client at that URL and the same data arrives as tools.'
  x-stream: 'wss://api.helious.io/v1/stream is the live WebSocket, which OpenAPI cannot describe as a path. One socket on every plan: live on Pro (2 connections a key) and Ultimate (5), delayed below Pro (one snapshot a minute). Messages: hello (mode names the lane), feed (items in the /v1/feed shape; a release print is kind post, category release, with the actual, forecast, previous and sigma in its text), prices, ndx, market_data, score (the Helious momentum score when it moves, in the /v1/score shape), and pong to a ping. The hel_ key goes in the Authorization: Bearer header, never a query parameter; no key opens the delayed lane. Documented at https://helious.io/developers/#stream and https://helious.io/developers/economic-calendar-api/#stream.'
  contact:
    name: Helious support
    email: support@helious.news
    url: https://helious.io/contact
  termsOfService: https://helious.news/terms
servers:
- url: https://api.helious.io
tags:
- name: Economic data
  description: Every tracked US economic series, the calendar, and release prints with their surprise scores.
paths:
  /v1/series:
    get:
      tags:
      - Economic data
      summary: All tracked economic series (v1 envelope)
      security:
      - {}
      - helious_key: []
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      parameters:
      - $ref: '#/components/parameters/fresh'
      operationId: getV1Series
      x-operation-id-source: derived
  /v1/series/{slug}:
    get:
      tags:
      - Economic data
      summary: One economic series with history (v1 envelope)
      security:
      - {}
      - helious_key: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: cpi
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '404':
          description: Unknown series
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      description: 'official_history is the published table of values: the newest 36 observations on every plan, and beyond them every observation inside your plan''s history window (10 years on Ultimate). consensus_history is the consensus record Helious holds for the release: rows (ConsensusRow, newest first, the same shape as /v1/calendar/history) inside your plan''s history window, at most 520, count, clamped (true when the plan''s window withheld older rows, which a deeper plan reads) and a note. These rows are held, not captured; prints carries Helious''s own captured first prints. Where the record runs past your window, the plan_limit wall counts its first day.'
      operationId: getV1SeriesBySlug
      x-operation-id-source: derived
  /v1/calendar:
    get:
      tags:
      - Economic data
      summary: The forward economic calendar
      description: 'Economic releases with forecasts, prior values and the actual once it prints, plus Fed speakers and auction times. Windowed: defaults to yesterday through the next 7 days, trimmed to the fields an answer is built from. Widen days_back / days_ahead for more, or filter by country. On the free tiers a print stays held for 60 minutes after it lands, the same hour /v1/feed holds the release card: its row shows status delayed and reveal_at in place of the actual. Paid plans see it live. A row''s forecast is the market consensus; a High-impact year-over-year inflation row whose consensus has not landed may instead carry a value Helious works from the month-over-month consensus and the index levels, and that row carries forecast_implied: true until the consensus replaces it. A row without the key carries the consensus.'
      security:
      - {}
      - helious_key: []
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      parameters:
      - name: days_back
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 0
          maximum: 90
        description: Days of already-printed events to include.
      - name: days_ahead
        in: query
        required: false
        schema:
          type: integer
          default: 7
          minimum: 0
          maximum: 365
        description: Days ahead to include.
      - name: country
        in: query
        required: false
        schema:
          type: string
          example: US
        description: Two-letter country or bloc (US, EU, GB, JP). Empty means everywhere.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 500
        description: Most events to return.
      - $ref: '#/components/parameters/fresh'
      operationId: getV1Calendar
      x-operation-id-source: derived
  /v1/calendar/history:
    get:
      tags:
      - Economic data
      summary: One release's consensus record
      description: 'One release''s consensus record, newest first: for each past print the consensus that stood, the first actual, the previous and the revised prior, with its surprise. Helious holds this record for every numeric release on its calendar for the US, the euro area, the UK, Japan and Germany, as far back as your plan''s history window reads (12 months on Starter, 24 on Pro, 10 years on Ultimate). These rows are held, not captured: Helious''s own captured first prints are the prints on /v1/series/{slug}. The rows follow your plan''s history window (1 day keyless, 7 days free, 12 months Starter, 24 months Pro, 10 years Ultimate), at most 520 rows a call. data carries event (name, country, slug where the release has a /v1/series hub, canon, unit, scale), rows, count and since (where this answer''s window starts). Where the record runs past your window, meta.clamped is true and plan_limit names the plan that reads further back; where no plan reads further, record_start says so. On the free tiers a print younger than 60 minutes is left out until the hour passes. A release dated ahead is on /v1/calendar, not here.'
      security:
      - {}
      - helious_key: []
      parameters:
      - name: event
        in: query
        required: true
        schema:
          type: string
          example: cpi
        description: 'The release: a /v1/series slug like cpi, a release name as the calendar prints it like Consumer Price Index (MoM), or that name with its country prefix like GB: Retail Sales (MoM).'
      - name: country
        in: query
        required: false
        schema:
          type: string
          example: GB
        description: US, EU, GB, JP or DE. Narrows a name several countries share.
      - name: since
        in: query
        required: false
        schema:
          type: string
          example: '2025-01-01'
        description: The oldest release date to include, never earlier than your plan's window.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 520
          minimum: 1
          maximum: 520
        description: Most rows to return, newest first.
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope. data.rows items are ConsensusRow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: 'An event the record does not hold (code unknown_event, with candidates: the nearest releases it holds, each with name, country, canon, slug, first, last and rows), or a country it does not hold (code unknown_country, with valid_country). Nothing is charged for a refusal.'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      operationId: getV1CalendarHistory
      x-operation-id-source: derived
  /api/seo/series-index:
    get:
      tags:
      - Economic data
      summary: All tracked economic series
      description: Every economic series Helious tracks (CPI, NFP, GDP, claims and more) with cadence, typical release time (ET), the latest captured print and the next scheduled release.
      responses:
        '200':
          description: Series list
          content:
            application/json:
              schema:
                type: object
      operationId: getApiSeoSeriesIndex
      x-operation-id-source: derived
  /api/seo/series/{slug}:
    get:
      tags:
      - Economic data
      summary: Print history for one economic series
      description: Newest captured prints (capped at 60; history_count reports the total in the capture window) with actual, forecast, previous and z-surprise, plus the latest card and next release for one series. The CSV at /api/seo/csv/series/{slug} is a capped sample of recent rows; the full history, including multi-year official backfill, comes through /v1/series/{slug}, where depth follows your plan. Valid slugs come from /api/seo/series-index.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: cpi
      responses:
        '200':
          description: Series detail
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Unknown series
      operationId: getApiSeoSeriesBySlug
      x-operation-id-source: derived
  /api/seo/csv/series/{slug}:
    get:
      tags:
      - Economic data
      summary: 'CSV sample: recent economic series prints'
      description: 'A capped sample: recent rows only, with a trailer line pointing to the API. Columns: date, actual, forecast, previous, z_surprise, label, source (helious-desk or official). The full history comes through /v1/series/{slug}, where depth follows your plan.'
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: cpi
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
        '404':
          description: Unknown series
      operationId: getApiSeoCsvSeriesBySlug
      x-operation-id-source: derived
  /api/seo/week:
    get:
      tags:
      - Economic data
      summary: Economic calendar for one ISO week
      description: 'The economic calendar for a given ISO week (default: current week) with forecasts and captured actuals.'
      parameters:
      - name: week
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{4}-W\d{2}$
        example: 2026-W32
      responses:
        '200':
          description: Week of events
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Bad week format
      operationId: getApiSeoWeek
      x-operation-id-source: derived
  /api/calendar:
    get:
      tags:
      - Economic data
      summary: Full merged economic calendar
      description: 'The complete forward calendar (economic releases, auctions, Fed events) as one JSON array. Prints follow the caller''s plan, as on /v1/calendar: without a paid key, a print younger than 60 minutes is held (no actual, capture.status delayed with reveal_at). Send a paid key as ''Authorization: Bearer hel_...'' to see prints live.'
      responses:
        '200':
          description: Calendar events
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
      operationId: getApiCalendar
      x-operation-id-source: derived
  /v1/earnings:
    get:
      tags:
      - Economic data
      summary: Mega-cap earnings dates and EPS
      description: When a US mega-cap reports, whether that date is confirmed or still an estimate, whether it prints before the open or after the close, the consensus EPS, and once it lands the reported EPS with its beat or miss. Pass symbol for one name.
      security:
      - {}
      - helious_key: []
      - helious_oauth:
        - market:read
      parameters:
      - name: symbol
        in: query
        required: false
        schema:
          type: string
        description: One or more tickers, comma separated, like AAPL. Empty returns every name tracked.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 40
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      operationId: getV1Earnings
      x-operation-id-source: derived
  /v1/treasury-issuance:
    get:
      summary: Monthly US Treasury issuance and the cash balance behind it
      description: 'How much the Treasury is selling and what it is holding: gross and net issuance by month, bills against coupons, the operating cash balance, and the quarterly refunding statement alongside it. Each measure carries its month, three month, six month and year windows already worked out. The latest reading answers on every tier, including keyless, because it is a single published figure. The monthly HISTORY behind it follows your plan''s window (7 days on a free key, 12 months Starter, 24 months Pro, 10 years Ultimate); a call that hits the window still returns the newest month and adds a `plan_limit` block naming the month it reached back to (on Ultimate, the deepest window, a `record_start` block instead: no plan reads further back).'
      tags:
      - Economic data
      parameters:
      - name: measures
        in: query
        required: false
        description: Comma-separated measure keys. Omit for all.
        schema:
          type: string
      - name: history
        in: query
        required: false
        description: Add the monthly series for each measure returned, back as far as your plan's history window allows.
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      security:
      - {}
      - helious_key: []
      operationId: getV1TreasuryIssuance
      x-operation-id-source: derived
components:
  parameters:
    fresh:
      name: fresh
      in: query
      required: false
      schema:
        type: boolean
      description: 'Not on Pro or Ultimate? Add fresh=1 to this request and this one call answers live (news, prints, auctions, boards and prices at the live instant) for 5 credits. Left out, Free, Squawk and Starter get the answer 60 minutes behind for 1 credit. With fewer than 5 credits left the live call is refused with out_of_credits and nothing is charged; the same call without the flag still answers for 1. Accepted and free on Pro and Ultimate, where the view is already live. Ignored without a key: a free account key has the flag. Over MCP the same flag is fresh: true in the tool''s arguments.'
  schemas:
    Envelope:
      type: object
      description: Every /v1 response. `summary` states the answer as one plain-English sentence and `source` says who to credit for it, both before the raw `data`, so the finished claim is the first thing a reader meets.
      properties:
        summary:
          type: string
          description: The answer as a sentence, with the numbers in it. Identical to the sentence the matching MCP tool returns.
        source:
          type: object
          description: Who to credit and where a reader can check the number.
          properties:
            name:
              type: string
              example: Helious
            url:
              type: string
              format: uri
              description: The Helious page backing this answer.
            cite_as:
              type: string
              example: Helious, https://helious.io/auctions
            attribution:
              type: string
            live:
              type: string
              description: How current these numbers are on YOUR plan, and how to ask for them again. Says the data is live only on a tier that serves it live.
        data:
          type: object
          description: The dataset itself.
        meta:
          type: object
          description: When it was true, and what your plan allows.
        plan_limit:
          type: object
          description: Present only when your plan moved the window AND Helious holds rows older than it. Says this is a plan limit rather than missing data, where the record begins (record_begins, on the lanes that say it), the plans that reach further, and the exact step to relay to the person you work for.
        record_start:
          type: object
          description: 'Present instead of plan_limit when you asked for more history than any plan reads here: record_begins is the first day any plan reads (null when there is none yet), your plan''s window already reaches it, older_rows_on_any_plan is false, and meta.clamped is false. No plan reaches further back, so there is nothing to upgrade for.'
  securitySchemes:
    helious_key:
      type: http
      scheme: bearer
      description: 'Your Helious API key, like hel_xxx, made on your helious.io account page (Account, then API keys). Every /v1 endpoint also works with no key at the sample tier: 1 day of history, news 1 hour behind, no market prices. A free account key gets 7 days and a rate budget of your own. Starter ($14.99/mo) takes the news live, reaches 12 months back and adds the Treasury curve 60 minutes behind; Pro ($39.99/mo) makes every price live with 24 months of history, the /v1/stream WebSocket included; Ultimate ($99/mo) reaches 10 years, allows commercial use and holds the live stream on 5 connections a key (Pro holds 2).'
    helious_oauth:
      type: oauth2
      description: Sign the person in instead of asking them for a key. Dynamic client registration is open, so your client can enrol itself; the one human step is the consent screen. Access tokens last an hour; ask for offline_access to get a rotating refresh token. Full details at https://helious.io/auth.md.
      flows:
        authorizationCode:
          authorizationUrl: https://helious.io/oauth/authorize
          tokenUrl: https://api.helious.io/oauth/token
          refreshUrl: https://api.helious.io/oauth/token
          scopes:
            market:read: Read Helious market data at that plan level.
            account:read: See which plan the account is on.
            openid: Confirm the account identity to your app.
            offline_access: Get a refresh token so you stay connected.