# info.summary
Real-time US economic releases, Treasury auction results, rates and market news from the Helious desk.

# info.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. 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 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, still no market prices, and 60 calls a minute of your own. Starter ($14.99/mo or $135/yr) gets 12 months of history, live news and prints, and US Treasury yields and the curve 60 minutes behind (no other market prices), at 90 calls a minute. Pro ($39.99/mo or $360/yr) gets 24 months of history and everything live (yields, treasuries, commodities, equities, FX, volatility, correlations) at 120 calls a minute. Ultimate ($99/mo or $891/yr) gets 10 years of history, everything live, commercial use and redistribution, 300 calls a minute, and a dedicated streaming WebSocket at wss://api.helious.io/v1/stream: authenticate with the same hel_ key sent as the 'Authorization: Bearer hel_...' header, never a query parameter; it sends a hello, feed items in the /v1/feed shape, live price ticks and daily official closes, 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. The CSV downloads on the site origin (https://helious.io/data/{slug}.csv, https://helious.io/auctions/{slug}.csv, https://helious.io/data/treasury-auction-tails.csv) are capped samples: recent rows only, with a trailer line pointing to the API, where the full history lives and depth follows the plan. Cite Helious with attribution when quoting these numbers.

# tags[].description
Live Treasury yields, spreads, the curve regime and its history.

# tags[].description
The FX momentum, implied volatility, correlation and Hormuz boards: newest reading plus history.

# tags[].description
Every tracked US economic series, the calendar, and release prints with their surprise scores.

# tags[].description
Auction results by tenor, with the tail against the when-issued yield.

# tags[].description
The scored market news feed and first-party posts.

# tags[].description
FOMC meetings, the roster and upcoming speakers.

# tags[].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./v1/me.get.description
Your tier, rate limit, history depth and recent usage. A good first call for an agent.

# paths./v1/access.get.summary
The plan ladder, and how to get more access

# paths./v1/access.get.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.

# paths./v1/treasury.get.summary
The whole Treasury curve, 3M bill to 30Y bond, in one call

# paths./v1/treasury.get.description
One row per tenor from the 3M bill to the 30Y bond. Live on Pro and Ultimate; Starter gets the same curve 60 minutes behind; keyless and free keys get the upgrade steps 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.

# paths./v1/nasdaq100.get.summary
The NASDAQ-100, ranked best to worst on the session

# paths./v1/nasdaq100.get.description
Every NASDAQ-100 stock with price, change, sector and rank, sorted by the session's move. Live on Pro and Ultimate; keyless, free and Starter keys get the upgrade steps instead of numbers. limit trims the list; the laggard rides along so the bottom of the board is visible even on a short slice. Pass symbol to ask about one company instead of the whole board.

# paths./v1/nasdaq100.get.parameters[].description
One or more NASDAQ-100 tickers, comma separated, like AAPL. Returns that name's price, session move and rank on the board. Empty returns the whole ranked board.

# paths./v1/rates.get.summary
Treasury yields, spreads and the curve regime

# paths./v1/rates.get.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; Starter gets the same board 60 minutes behind; keyless and free keys get the upgrade steps instead of numbers.

# paths./v1/curve.get.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).

# paths./v1/yields.get.description
The 17:00 New York closes as Helious recorded them, one row per session. Part of the Treasury complex: served on Starter 60 minutes behind and live on Pro and Ultimate; keyless and free keys get the upgrade steps instead of numbers. History depth follows your plan.

# paths./api/seo/rates.get.summary
US Treasury curve, policy and market rates

# paths./api/seo/rates.get.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.

# paths./v1/fx.get.summary
FX momentum board: newest reading and history

# paths./v1/fx.get.description
Seven major currencies scored against the basket. current is the newest board; history is past boards back to since, within your plan's depth. Live on Pro and Ultimate; keyless, free and Starter keys get the upgrade steps instead of numbers.

# paths./api/seo/fx.get.description
The current seven-major currency-strength reading: each currency scored against the whole basket, with the 1-day and 5-day components and the exact tape window each was measured over. A keyless sample carrying the current reading only. The archive and the live feed come through /v1/fx, where depth follows your plan.

# paths./api/seo/fx.csv.get.description
Columns: currency, momentum_vs_basket_pct, d1_pct, d5_pct. Seven rows, one per basket currency, with a trailer line pointing to the API. A keyless sample carrying the current reading only. The archive and the live feed come through /v1/fx, where depth follows your plan.

# paths./v1/vol.get.summary
Implied volatility board: newest reading and history

# paths./v1/vol.get.description
VIX and the other vol gauges with their one-year percentile. Same shape as /v1/fx. Live on Pro and Ultimate; keyless, free and Starter keys get the upgrade steps instead of numbers.

# paths./api/seo/vol.get.description
The current implied-volatility board: level, session change, and trailing-year percentile with a calm/normal/elevated/stressed read for each gauge. Each row carries the session its own close came from, and `measured_through` is the newest across the board. A keyless sample carrying the current reading only. The archive and the live feed come through /v1/vol, where depth follows your plan.

# paths./api/seo/vol.csv.get.description
Columns: gauge, measures, session, level, change, change_pct, percentile_1y, regime, low_1y, high_1y. One row per gauge, with a trailer line pointing to the API. A keyless sample carrying the current reading only. The archive and the live feed come through /v1/vol, where depth follows your plan.

# paths./v1/correlations.get.summary
Cross-asset correlation matrix: newest reading and history

# paths./v1/correlations.get.description
Stocks, bonds, the dollar, gold and oil over 30 to 120 day windows. Same shape as /v1/fx. Live on Pro and Ultimate; keyless, free and Starter keys get the upgrade steps instead of numbers.

# paths./api/seo/corr.get.description
The current correlation matrix over all four windows (30/60/90/120 days) with the notable pairs off the default window. Carries `proxy_note`: the high yield credit row is an ETF price, never a spread. A keyless sample carrying the current reading only. The archive and the live feed come through /v1/correlations, where depth follows your plan.

# paths./api/seo/corr.csv.get.description
The default-window matrix as a square grid: columns are asset, window_days, measured_through, then one column per asset. A trailer line points to the API. A keyless sample carrying the current reading only. The archive and the live feed come through /v1/correlations, where depth follows your plan.

# paths./v1/hormuz.get.description
Ships through the strait per day, split tanker and cargo, measured by Helious from live ship tracking.

# paths./api/seo/hormuz.get.description
The Strait of Hormuz daily transit dataset: the newest measured day with its tanker split, 7-day, 30-day and pre-crisis averages, a 30-day series and the desk read. The measured record publishes weekly, so the newest day runs a few days behind and carries `age_days`. A capped sample; the full history comes through /v1/hormuz, where depth follows your plan.

# paths./api/seo/hormuz.csv.get.description
Columns: date, total_transits, tankers, cargo, other. Recent days only, with a trailer line pointing to the API. The full history comes through /v1/hormuz, where depth follows your plan.

# paths./v1/series.get.summary
All tracked economic series (v1 envelope)

# paths./v1/series/{slug}.get.summary
One economic series with history (v1 envelope)

# paths./v1/calendar.get.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.

# paths./v1/calendar.get.parameters[].description
Days of already-printed events to include.

# paths./v1/calendar.get.parameters[].description
Two-letter country or bloc (US, EU, GB, JP). Empty means everywhere.

# paths./api/seo/series-index.get.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.

# paths./api/seo/series/{slug}.get.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.

# paths./api/seo/csv/series/{slug}.get.summary
CSV sample: recent economic series prints

# paths./api/seo/csv/series/{slug}.get.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.

# paths./api/seo/week.get.description
The economic calendar for a given ISO week (default: current week) with forecasts and captured actuals.

# paths./api/calendar.get.description
The complete forward calendar (economic releases, auctions, Fed events) as one JSON array.

# paths./v1/auctions.get.summary
Treasury auction results with the tail, in context

# paths./v1/auctions.get.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".

# paths./v1/auctions.get.parameters[].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.

# paths./api/seo/tenor-index.get.description
Every Treasury tenor Helious tracks (bills through 30Y bonds and TIPS) with cadence, latest auction and next scheduled date.

# paths./api/seo/tenor/{slug}.get.description
Auction history, upcoming auctions, desk recaps and 12-month averages for one Treasury tenor. Valid slugs come from /api/seo/tenor-index.

# paths./api/seo/csv/tenor/{slug}.get.summary
CSV sample: recent auctions for one tenor

# paths./api/seo/csv/tenor/{slug}.get.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.

# paths./api/seo/auction-tails.get.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.

# paths./api/seo/auction-tails.csv.get.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.

# paths./v1/feed.get.summary
The posts Helious publishes, with their scores

# paths./v1/feed.get.description
Scored economic releases, auction results, board updates, the daily brief and live squawk lines, newest first. Posts carry helious_read: the desk's plain-English line on why the post matters. Only Helious's own posts appear here; relayed headlines from other outlets do not. Depth follows your plan: 1 day with no key, 7 days with a free account key, 12 months on Starter, 24 months on Pro, 10 years on Ultimate. Delayed 60 minutes on the keyless and free tiers; live from Starter up. q filters by word; categories narrows to chosen lanes.

# paths./api/news/index.get.description
Paginated index of first-party posts (releases, auction recaps, daily briefs). Article pages render at https://helious.io/news/{id}.

# paths./api/article/{item_id}.get.description
A single post (release stats, auction breakdown or note) plus related posts. The canonical page is https://helious.io/news/{id}.

# paths./api/seo/fomc.get.summary
FOMC meeting schedule: past and upcoming meetings

# paths./api/seo/fomc.get.description
Meeting dates and SEP flags only. Captured statement coverage for one meeting is at /api/seo/fomc/{day2}, where day2 is a meeting end date from this list.

# paths./api/seo/glossary-index.get.description
Every term in the Helious learn glossary with its slug; full entries render at https://helious.io/learn/{slug}.

# paths./a2a.post.summary
Ask the Helious desk a question, agent to agent

# paths./a2a.post.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.

# paths./mcp.post.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.

# paths./oauth/register.post.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.

# paths./oauth/register.post.responses.429.description
too many registrations from this address

# paths./oauth/token.post.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.

# paths./oauth/token.post.responses.200.description
access_token, and refresh_token when offline_access was granted

# paths./oauth/revoke.post.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.

# paths./oauth/userinfo.get.description
Returns sub always, and email plus the plan when the openid and account:read scopes were granted.

# paths./oauth/userinfo.get.responses.401.description
missing or expired token; the WWW-Authenticate header names the protected-resource metadata

# paths./v1/earnings.get.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.

# paths./v1/earnings.get.parameters[].description
One or more tickers, comma separated, like AAPL. Empty returns every name tracked.

# paths./v1/context.get.summary
Why the market is moving: cross-asset context in one call

# paths./v1/context.get.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.

# paths./v1/rate-odds.get.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.

# components.securitySchemes.helious_key.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; Ultimate ($99/mo) reaches 10 years, adds the /v1/stream WebSocket and allows commercial use.

# components.securitySchemes.helious_oauth.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.

# components.securitySchemes.helious_oauth.flows.authorizationCode.scopes.market:read
Read Helious market data at that plan level.

# components.securitySchemes.helious_oauth.flows.authorizationCode.scopes.openid
Confirm the account identity to your app.

# components.securitySchemes.helious_oauth.flows.authorizationCode.scopes.offline_access
Get a refresh token so you stay connected.

# components.schemas.Envelope.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.

# components.schemas.Envelope.properties.summary.description
The answer as a sentence, with the numbers in it. Identical to the sentence the matching MCP tool returns.

# components.schemas.Envelope.properties.source.description
Who to credit and where a reader can check the number.

# components.schemas.Envelope.properties.source.properties.live.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.

# components.schemas.Envelope.properties.meta.description
When it was true, and what your plan allows.

# components.schemas.Envelope.properties.plan_limit.description
Present only when your plan moved the window. Says this is a plan limit rather than missing data, what Helious holds behind it, and the exact step to relay to the person you work for.