Helious Treasury auctions API

openapi: 3.2.0
info:
  title: Helious Public Treasury auctions 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: Treasury auctions
  description: Auction results by tenor, with the tail against the when-issued yield.
paths:
  /v1/auctions:
    get:
      tags:
      - Treasury auctions
      summary: Treasury auction results with the tail, in context
      description: 'High yield, bid-to-cover, the tail against the when-issued yield, and who bought, per auction, within your plan''s depth. tail_bps is null for bills, which have no when-issued market, and for any auction whose when-issued print was not captured; a negative tail_bps is a stop-through (the auction cleared below the when-issued yield, i.e. strong demand). Every row also carries vs_12m: that tenor''s trailing twelve-auction averages for the tail, bid-to-cover and bidder split (withheld under 3 priors), plus pctile (the print''s rank in the tenor''s full captured history, withheld under 12 priors) and a significance note like ''the weakest bid-to-cover since 2024-03-12'' when a print is beyond everything back at least a year. The print arrives with its own norm, so an agent can judge it without fetching history. The dataset is complete back through the official record: `record` marks each row desk (captured live by Helious, may carry a tail) or official (TreasuryDirect backfill, no tail: TD does not publish when-issued yields). Pass `tenor` to ask about one part of the curve, which is what answers "how did the last 10-year auction go". With one tenor (tenor=10y), the answer adds stop_history: the stop yield of every auction of that tenor from the official record, as [date, yield] rows inside your plan''s history window (10 years on Ultimate).'
      security:
      - {}
      - helious_key: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
      - name: tenor
        in: query
        required: false
        schema:
          type: string
        description: 'One tenor, like 10-year-note, 30-year-bond or 26-week-bill. Plain forms work too (''10y'', ''30 year''), as does a whole class: bills, notes, bonds, tips, frn. Reopenings of a tenor are included. An unknown value returns 400 with the list of valid tenors.'
      - $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: getV1Auctions
      x-operation-id-source: derived
  /api/seo/tenor-index:
    get:
      tags:
      - Treasury auctions
      summary: All tracked Treasury auction tenors
      description: Every Treasury tenor Helious tracks (bills through 30Y bonds and TIPS) with cadence, latest auction and next scheduled date.
      responses:
        '200':
          description: Tenor list
          content:
            application/json:
              schema:
                type: object
      operationId: getApiSeoTenorIndex
      x-operation-id-source: derived
  /api/seo/tenor/{slug}:
    get:
      tags:
      - Treasury auctions
      summary: Auction history for one tenor
      description: Auction history, upcoming auctions, desk recaps and 12-month averages for one Treasury tenor. Valid slugs come from /api/seo/tenor-index.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: 10-year-note
      responses:
        '200':
          description: Tenor detail
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Unknown tenor
      operationId: getApiSeoTenorBySlug
      x-operation-id-source: derived
  /api/seo/csv/tenor/{slug}:
    get:
      tags:
      - Treasury auctions
      summary: 'CSV sample: recent auctions for one tenor'
      description: 'A capped sample: recent rows only, with a trailer line pointing to the API. Columns: auction_date, cusip, high_yield, when_issued_yield, tail_bps, bid_to_cover, indirect_pct, direct_pct, dealer_pct, verdict, issue. The full history comes through /v1/auctions, where depth follows your plan.'
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: 10-year-note
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
        '404':
          description: Unknown tenor
      operationId: getApiSeoCsvTenorBySlug
      x-operation-id-source: derived
  /api/seo/auction-tails:
    get:
      tags:
      - Treasury auctions
      summary: Treasury auction tails sample (JSON)
      description: 'The recent slice of the cross-tenor auction dataset: the tail (high yield minus when-issued), bid-to-cover, bidder split and desk verdict per auction. A capped sample; the full history comes through /v1/auctions, where depth follows your plan.'
      responses:
        '200':
          description: Auction tails
          content:
            application/json:
              schema:
                type: object
      operationId: getApiSeoAuctionTails
      x-operation-id-source: derived
  /api/seo/auction-tails.csv:
    get:
      tags:
      - Treasury auctions
      summary: Treasury auction tails sample (CSV)
      description: 'A capped sample: recent rows only, with a trailer line pointing to the API. Columns: auction_date, tenor, type, high_yield, when_issued_yield, tail_bps, bid_to_cover, indirect_pct, direct_pct, dealer_pct, verdict, issue. The full history comes through /v1/auctions, where depth follows your plan.'
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
      operationId: getApiSeoAuctionTailsCsv
      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.