Helious Your key API

openapi: 3.2.0
info:
  title: Helious Public Your key 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: Your key
  description: What your key is and what it may do.
paths:
  /v1/me:
    get:
      tags:
      - Your key
      summary: What your key may do
      description: Your tier, rate limit, history depth and recent usage. A good first call for an agent.
      security:
      - {}
      - helious_key: []
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
      operationId: getV1Me
      x-operation-id-source: derived
  /v1/access:
    get:
      tags:
      - Your key
      summary: The plan ladder, and how to get more access
      description: 'Works without a key. Your tier, every plan, and the exact next step to relay to your user: how to make a free account, get a key, or subscribe. Agents should read this instead of guessing.'
      security:
      - {}
      - helious_key: []
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
      operationId: getV1Access
      x-operation-id-source: derived
  /v1/build-plan:
    get:
      tags:
      - Your key
      summary: What to build with Helious and how
      description: Works without a key and is never charged. For a stated goal (a macro system, a trading algorithm, a macro forecast) the calls in order, what each returns, what a pass and a month cost in credits at your cadence, what this caller has left, and the plan that covers it. With no goal, the three recipes in short form. The same answer as the get_build_plan MCP tool.
      parameters:
      - name: goal
        in: query
        required: false
        schema:
          type: string
        description: What you are building, in your words. Empty returns the three recipes in short form.
      - name: cadence
        in: query
        required: false
        schema:
          type: string
        description: How often it will run, like every 15 minutes, hourly, daily, every trading day or weekly. Daily when empty, and the answer says so.
      - name: language
        in: query
        required: false
        schema:
          type: string
        description: python, javascript or another language, to point at the right sample.
      - name: client
        in: query
        required: false
        schema:
          type: string
        description: The client or stack it runs in, like claude, chatgpt, cursor or a script.
      security:
      - {}
      - helious_key: []
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
      operationId: getV1BuildPlan
      x-operation-id-source: derived
components:
  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.