Helious Rates and curve API

openapi: 3.2.0
info:
  title: Helious Public Rates and curve 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: Rates and curve
  description: Live Treasury yields, spreads, the curve regime and its history.
paths:
  /v1/treasury:
    get:
      tags:
      - Rates and curve
      summary: The whole Treasury curve, 3M bill to 30Y bond, in one call
      description: One row per tenor from the 3M bill to the 30Y bond. Live on Pro and Ultimate; Free, Squawk and Starter get the same curve 60 minutes behind for 1 credit and live for 5 with fresh=1; without a key the upgrade steps come instead of numbers. The regime label comes with it. Each tenor also carries its 52-week range, one-year and ten-year percentiles (range_52w, pct_1y, pct_10y) and a significance note like 'highest close since 2007' when the level is beyond everything back at least a year.
      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: getV1Treasury
      x-operation-id-source: derived
  /v1/rates:
    get:
      tags:
      - Rates and curve
      summary: Treasury yields, spreads and the curve regime
      description: The yields board, the 2s10s and other spreads, and the current curve regime (bull or bear, steepener or flattener) with the time it flipped. Live on Pro and Ultimate; Free, Squawk and Starter get the same board 60 minutes behind for 1 credit and live for 5 with fresh=1; without a key the upgrade steps come instead of numbers.
      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: getV1Rates
      x-operation-id-source: derived
  /v1/curve:
    get:
      tags:
      - Rates and curve
      summary: Curve regime now, plus every past flip
      description: The current regime and the recorded history of regime changes. Use since to go back in time; your plan sets how far back you may go (1 day with no key, 7 days with a free account key, 12 months on Starter, 24 months on Pro, 10 years on Ultimate). Below Pro the current regime and the flips run 60 minutes behind for 1 credit (live for 5 with fresh=1), and delayed_to names the cutoff.
      security:
      - {}
      - helious_key: []
      parameters:
      - name: since
        in: query
        required: false
        schema:
          type: string
        example: '2026-07-01'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 200
      - $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: getV1Curve
      x-operation-id-source: derived
  /v1/yields:
    get:
      tags:
      - Rates and curve
      summary: Treasury yields per session, back to 2000
      description: 'One row per session: the 17:00 New York closes as Helious recorded them, and before that ledger began the official daily Treasury yields, back to 2000, in the same shape and marked record ''official''. Part of the Treasury complex: served on Free, Squawk and Starter (end-of-day rows, 1 credit) and on Pro and Ultimate; without a key the upgrade steps come instead of numbers. The official rows come when you ask further back than the 17:00 record (an earlier since, or before); a call with neither stays on the 17:00 record. History depth follows your plan (10 years on Ultimate).'
      security:
      - {}
      - helious_key: []
      parameters:
      - name: since
        in: query
        required: false
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Newest date to include, like 2018-12-31, to page further back.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 120
      - $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: getV1Yields
      x-operation-id-source: derived
  /api/seo/rates:
    get:
      tags:
      - Rates and curve
      summary: US Treasury curve, policy and market rates
      description: 'Treasury curve points (1M to 30Y), 2s10s and 3m10s spreads, effective fed funds, SOFR, VIX and high-yield OAS: value, one-day delta and as-of observation date per series.'
      responses:
        '200':
          description: Rates snapshot
          content:
            application/json:
              schema:
                type: object
      operationId: getApiSeoRates
      x-operation-id-source: derived
  /v1/context:
    get:
      tags:
      - Rates and curve
      summary: 'Why the market is moving: cross-asset context in one call'
      description: 'The whole cross-asset board (equities, the Treasury curve with its regime, FX, volatility, commodities and credit ETF proxies), every scored economic release behind it, and the Helious desk''s read on what is driving the session. The read characterises the session rather than grading itself: event-driven (a print explains it and the tape confirms), event-adjacent (a print landed but the tape has not confirmed it), flow-driven (no scheduled catalyst, so positioning rather than data) or quiet. It is framed by the regime yields and stocks have actually been trading in, measured over Helious''s own reaction archive. Start here for any ''why is the market doing this'' question: it replaces five separate calls. Credit spreads ride along as measured high-yield and investment-grade OAS (daily index closes from FRED); HYG and LQD appear beside them as clearly labelled ETF price proxies, never as spreads. Prices in this answer are live on Pro and Ultimate; below those plans the price boards answer with the upgrade steps instead of numbers, though Starter still gets the Treasury curve 60 minutes behind.'
      security:
      - {}
      - helious_key: []
      - helious_oauth:
        - market:read
      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: getV1Context
      x-operation-id-source: derived
  /v1/rate-odds:
    get:
      tags:
      - Rates and curve
      summary: Fed rate cut and hike odds
      description: 'What the fed funds futures market prices for each remaining FOMC meeting: the probability of a cut or a hike, the implied effective rate after each one, and the total move priced across the path. Computed by Helious from settlement prices against the EFFECTIVE fed funds rate, not the midpoint of the target range, because the contracts settle on the effective rate and the gap between the two would otherwise read as a probability. Live on every plan: a settlement price and a daily published rate have nothing to delay.'
      responses:
        '200':
          description: The priced path.
          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: getV1RateOdds
      x-operation-id-source: derived
  /v1/rate-path:
    get:
      summary: Every listed SOFR and fed funds contract, priced now and a year ago
      description: 'The whole quoted strip on both lanes: three-month SOFR futures and 30-day fed funds futures, every contract with the rate it implies now, six months ago and twelve months ago, which quarters it covers, which FOMC decisions fall inside it, and the pack it belongs to. Use it to see how the market''s view of the path has moved rather than only where it sits. These are traded prices, but the same numbers are published on the public rate path page, so this answers on every tier, including keyless, and is never delayed.'
      tags:
      - Rates and curve
      parameters:
      - name: lane
        in: query
        required: false
        description: 'One lane only: sr3 for three-month SOFR, ff for fed funds. Omit for both.'
        schema:
          type: string
      - name: history
        in: query
        required: false
        description: Add each contract's own daily run of implied rates.
        schema:
          type: boolean
          default: false
      - name: days
        in: query
        required: false
        description: Days of that daily run to include when history is true.
        schema:
          type: integer
      - $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: getV1RatePath
      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.