Helious Agent sign-in and A2A API

openapi: 3.2.0
info:
  title: Helious Public Agent sign-in and A2A 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: Agent sign-in and A2A
  description: OAuth 2.1 so an agent can act for a person without a pasted key, and the agent-to-agent endpoint for asking the desk a question in plain words.
paths:
  /a2a:
    post:
      tags:
      - Agent sign-in and A2A
      summary: Ask the Helious desk a question, agent to agent
      description: A2A JSON-RPC. Send a question as a text part and get a completed Task back carrying the answer sentence, the source page and the full data. Implements message/send, tasks/get and tasks/cancel. Works with no credential at the sample tier. The agent card is at https://helious.io/.well-known/agent-card.json.
      security:
      - {}
      - helious_key: []
      - helious_oauth:
        - market:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - id
              - method
              - params
              properties:
                jsonrpc:
                  type: string
                  example: '2.0'
                id:
                  type: integer
                  example: 1
                method:
                  type: string
                  example: message/send
                params:
                  type: object
                  example:
                    message:
                      role: user
                      kind: message
                      messageId: m1
                      parts:
                      - kind: text
                        text: What is the 2s10s spread right now?
      responses:
        '200':
          description: JSON-RPC response carrying an A2A Task
          content:
            application/json:
              schema:
                type: object
        '202':
          description: Notification accepted, no body
      operationId: postA2a
      x-operation-id-source: derived
  /mcp:
    post:
      tags:
      - Agent sign-in and A2A
      summary: Model Context Protocol endpoint
      description: Stateless streamable-HTTP MCP. 20+ tools over the same data as /v1, with identical answer sentences. Also reachable at https://helious.io/mcp. Server card at https://helious.io/.well-known/mcp/server-card.json.
      security:
      - {}
      - helious_key: []
      - helious_oauth:
        - market:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  example: '2.0'
                id:
                  type: integer
                  example: 1
                method:
                  type: string
                  example: tools/list
                params:
                  type: object
      responses:
        '200':
          description: JSON-RPC response
          content:
            application/json:
              schema:
                type: object
        '202':
          description: Notification accepted, no body
      operationId: postMcp
      x-operation-id-source: derived
  /oauth/register:
    post:
      tags:
      - Agent sign-in and A2A
      summary: Register your client (RFC 7591)
      description: 'Open dynamic client registration, no human step. Public clients only: there is no client secret and PKCE S256 is required. A registered client can do nothing until a person completes the consent screen.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - redirect_uris
              properties:
                client_name:
                  type: string
                  example: My market agent
                redirect_uris:
                  type: array
                  items:
                    type: string
                  example:
                  - http://127.0.0.1:45999/callback
                grant_types:
                  type: array
                  items:
                    type: string
                  example:
                  - authorization_code
                  - refresh_token
                response_types:
                  type: array
                  items:
                    type: string
                  example:
                  - code
                token_endpoint_auth_method:
                  type: string
                  example: none
                scope:
                  type: string
                  example: market:read offline_access
      responses:
        '201':
          description: client_id issued
          content:
            application/json:
              schema:
                type: object
        '400':
          description: invalid client metadata or redirect_uri
        '429':
          description: too many registrations from this address
      operationId: postOauthRegister
      x-operation-id-source: derived
  /oauth/token:
    post:
      tags:
      - Agent sign-in and A2A
      summary: Exchange a code, or refresh
      description: 'grant_type=authorization_code with code_verifier, or grant_type=refresh_token. Form-encoded per the spec; JSON is also accepted. Refresh tokens rotate: store the new one and discard the old, because replaying a retired token revokes the whole chain.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              properties:
                grant_type:
                  type: string
                  example: authorization_code
                code:
                  type: string
                code_verifier:
                  type: string
                client_id:
                  type: string
                redirect_uri:
                  type: string
                refresh_token:
                  type: string
      responses:
        '200':
          description: access_token, and refresh_token when offline_access was granted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: invalid_grant, invalid_request or unsupported_grant_type
      operationId: postOauthToken
      x-operation-id-source: derived
  /oauth/revoke:
    post:
      tags:
      - Agent sign-in and A2A
      summary: Revoke a refresh token (RFC 7009)
      description: 'Always answers 200, including for a token that never existed: saying which guesses were real would be an oracle. Access tokens are stateless and expire within the hour.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  example: refresh_token
      responses:
        '200':
          description: acknowledged
      operationId: postOauthRevoke
      x-operation-id-source: derived
  /oauth/userinfo:
    get:
      tags:
      - Agent sign-in and A2A
      summary: Who this token belongs to
      description: Returns sub always, and email plus the plan when the openid and account:read scopes were granted.
      security:
      - helious_oauth:
        - openid
      responses:
        '200':
          description: claims
          content:
            application/json:
              schema:
                type: object
        '401':
          description: missing or expired token; the WWW-Authenticate header names the protected-resource metadata
      operationId: getOauthUserinfo
      x-operation-id-source: derived
components:
  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.