What to build with the Helious API

Three things people build on Helious: a macro system that knows which regime the US economy and the rates market are in, a trading algorithm that reacts to the print and the auction in seconds, and a macro forecast anchored on what markets already price. This page maps every endpoint and every MCP tool to each one, with the first call to make.

All three need the same thing from their data: a reading, not just a number. On Helious a release arrives with its forecast, its previous and its surprise in standard deviations. An auction arrives with its tail and a verdict. A headline arrives with a score for bonds and a score for stocks. The curve arrives with its regime and the time it flipped. Your code starts from the reading instead of rebuilding it.

The short version

Why the data is good to build on

• Scored on arrival. Every release carries actual, forecast, previous and sigma, the surprise in standard deviations against that release's own history, plus a word for it from MAJOR MISS to MAJOR BEAT. A CPI miss and a payrolls beat sit on one ruler.
• Two channels on every news item. score and direction for bonds, equity_score and equity_direction for stocks, each from -10 to +10, with a topic and a one-line helious_read. One story can be bullish for bonds and bearish for stocks, and the item says so.
• Context travels with the number. An auction carries its 12-auction averages and a percentile. A release level carries its percentile across its own history, back to 1983 for core CPI. A yield carries its 52-week range. The curve carries its regime and every past flip.
• Captured first-hand, with the latency published. Helious reads each US print as it publishes and measures how long that took. In the 7 days to 31 October 2026 the median was 12 seconds and nine in ten landed within 67 seconds. The live figure is at /api/seo/latency-stats.
• One shape on every plan. Every plan sees the same endpoints and the same fields, and the stream sends feed items in the /v1/feed shape. Code written with no key keeps working when the key upgrades.
• It says what it does not know. A print your plan cannot see yet reads status: delayed with reveal_at. /v1/context names a cause only when a scored release printed in the window, lists the checks its read passed and lists what it does not cover. A system can gate on those fields instead of guessing.
• Built for agents as well as code. Every answer opens with a summary sentence an AI can quote, and the MCP server at https://api.helious.io/mcp serves the same data as 25 tools.
• Priced for one builder. Free to start, $14.99 a month for live prints and $39.99 for everything live, with no contract. What it costs.

Build a macro system

A macro system classifies the state of the economy and the market, then decides what that state favours. Build it in layers. Each layer below is one or two calls, and each call returns the reading with the level.

A first regime read

import requests

API = "https://api.helious.io"
H = {"Authorization": "Bearer hel_your_key_here"}   # or drop it: these three answer with no key

def data(path, **params):
    r = requests.get(API + path, params=params, headers=H, timeout=15)
    r.raise_for_status()
    return r.json()["data"]

infl = {m["key"]: m for m in data("/v1/inflation", measures="core_pce")["measures"]}
jobs = {m["key"]: m for m in data("/v1/jobs", measures="payrolls")["measures"]}
odds = data("/v1/rate-odds")

inflation = "heating" if infl["core_pce"]["a3"] > infl["core_pce"]["yoy"] else "cooling"
labour = "slowing" if jobs["payrolls"]["m3"] < jobs["payrolls"]["m12"] / 12 else "steady"
policy = "tightening" if odds["path_total"]["change_bps"] > 0 else "easing"
print(inflation, labour, policy)

On 31 October 2026 it printed cooling steady tightening: core PCE's 3-month annualised rate of 2.90% sat under its 3.12% year rate, payrolls averaged 50,700 a month over 3 months against 41,300 over 12, and the fed funds strip priced 54bp of hikes through December 2027. Add the curve regime from /v1/rates and the session driver from /v1/context on Pro, and the labels become a state your strategy can switch on.

Build a trading algorithm

An event-driven algorithm needs four things: the schedule, the print the moment it lands, a size for the surprise, and a filter for the regime it is trading in. Helious supplies each one.

1. Know when. /v1/calendar returns each event's datetime_utc, impact and forecast up to 365 days ahead. Load it before the session, arm the strategy for the High-impact rows, or stand it down around them.
2. Hear the print. wss://api.helious.io/v1/stream pushes a feed message the moment a release, an auction or a headline lands, in the /v1/feed shape. Pro and Ultimate run the live lane. Every plan below gets the same messages once a minute, delayed.
3. Size the surprise. On a calendar row, sigma is the surprise against that release's own history, so one threshold works across CPI, payrolls and the PMIs. On a feed item, score is the bond read and equity_score the stock read.
4. Trade the auction. /v1/auctions gives tail_bps against the when-issued yield, bid to cover against its 12-auction average, the dealer share and a STRONG, IN LINE or WEAK verdict, read within seconds of the result.
5. Filter the headlines. /v1/feed carries the wire headlines with both scores. A re-headlined article updates its own item, and thread_id is the same for every version of a story, so count stories by it. Narrow with topics=geo,energy or q.
6. Know the regime. /v1/context says whether the session is event-driven, flow-driven or quiet, and whether yields and stocks have lately traded a growth or a rates story. /v1/vol and /v1/correlations show when the usual relationships break.
7. Pick the names. /v1/nasdaq100 ranks the index on the session with each stock's sector, and /v1/earnings gives each mega-cap's date, session, consensus EPS and the beat or miss once it files.

Listen for the print

import asyncio, json, websockets   # websockets 14 or later

async def run():
    async with websockets.connect(
        "wss://api.helious.io/v1/stream",
        additional_headers={"Authorization": "Bearer hel_your_key_here"},
    ) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            if msg["type"] == "hello":
                print("lane:", msg.get("mode"))          # live on Pro, delayed below
            elif msg["type"] == "feed":
                for item in msg.get("items", []):
                    if item.get("category") in ("release", "auction") and abs(item.get("score") or 0) >= 5:
                        print(item["created_at"], item["score"], item.get("equity_score"), item["title"])

asyncio.run(run())

The first messages are a hello naming your lane, then a snapshot of the feed, the price board, the NASDAQ-100 and the daily closes, so the strategy holds state from the first second. A feed message can carry removed ids for a withdrawn post: drop them.

Develop a macro forecast

A forecast is only useful against a baseline. Helious gives you three: what markets price, what the nowcasts say, and what the consensus expects for the next print. Your edge is the gap, and the sigma on the next print grades it.

1. Start from what is priced. /v1/rate-path returns 16 quarterly SOFR futures and 48 monthly fed funds contracts, each with its implied rate now and six and twelve months ago. /v1/rate-odds turns the fed funds strip into a probability per meeting. On 31 October 2026 it priced 70% odds of a 25bp hike on 9 December and 54bp of hikes through December 2027.
2. Read the nowcasts. /v1/series/gdpnow tracks growth in the current quarter between releases, and the michigan-1y-inflation and michigan-5y-inflation series give household inflation expectations.
3. Build the inflation path. /v1/inflation?history=true returns every measure's monthly series with the 1, 3 and 6-month annualised rates worked out, and says which parts of the basket drive the rate.
4. Build the jobs path. /v1/jobs?history=true returns payrolls by sector with contributions that sum to the headline exactly, plus weekly claims, the earliest read on the labour market.
5. Add supply. /v1/treasury-issuance gives net marketable borrowing, the bill, note and bond split, the Treasury's cash balance and the refunding schedule, the inputs to a view on term premium.
6. Know the reaction function. /api/fed/roster lists the voters and their lean. FOMC minutes and Fed speeches arrive in /v1/feed with a digest stating the hawkish or dovish lean, with quotes checked word for word.
7. Grade yourself. Before a release, /v1/calendar holds the consensus your number has to beat. After it, the actual and its sigma show how far the consensus missed, so you can log your own miss on the same ruler.

Your number against the run rate

import requests

def data(path, **params):
    r = requests.get("https://api.helious.io" + path, params=params, timeout=15)
    r.raise_for_status()
    return r.json()["data"]

core = data("/v1/inflation", measures="core_cpi")["measures"][0]
nxt = data("/v1/series/core-cpi")["next"]
run_rate = ((1 + core["a3"] / 100) ** (1 / 12) - 1) * 100
print(f"3-month run rate {run_rate:.2f}% a month")
print(f"consensus for {nxt['datetime_utc'][:10]}: {nxt['forecast'] or 'not set yet'}")

On 31 October 2026 it printed a run rate of 0.28% a month for core CPI, with the consensus for the 10 November print not yet set. Your forecast goes beside both. Both calls answer with no key.

Every endpoint by use case

Core: the job is hard to build without it. Yes: it adds to the job. Live from: the lowest plan that sees it live. Below that plan the endpoint still answers in the same shape: prints and news an hour behind, prices an hour behind on a free key and on Starter, and no prices at all with no key. The MCP column lists all 25 tools.

What it costs

Every plan sees the same endpoints and the same response shapes, so code written on the free tier keeps working when you upgrade. A data call is 1 credit.

For the macro job, Starter at $14.99 a month is the lowest published paid price among the data APIs Helious compares itself with. Financial Modeling Prep starts at $29 a month, or $19 billed yearly. Alpha Vantage starts at $49.99. Finnhub keeps economic data on a $3,500 a month plan. Trading Economics quotes on request. FRED is free and is the official record, but carries no forecast, no surprise score and no auction read. Prices as of October 2026, from each vendor's own page.

Questions

What can you build with the Helious API?

Three things most often: a macro system that classifies where growth, inflation, policy and the Treasury curve stand; an event-driven trading algorithm that reacts to releases, Treasury auctions and headlines as they land; and a macro forecast built from what markets price, the inflation and jobs paths and the consensus. The REST API, the WebSocket stream and the MCP server serve the same data.

Is the Helious API good for a trading algorithm?

For US macro events, yes. Every release arrives with its surprise in standard deviations, every Treasury auction with its tail and a verdict, and every headline with a bond score and a stock score. Pro ($39.99 a month) pushes all of it live over wss://api.helious.io/v1/stream, with live prices, in the same shape as the REST feed.

Can I backtest on Helious data?

Partly. The official histories behind each economic series run back decades and the auction results back years, and a release level carries its percentile across its own history. The scored record Helious captured itself, with the forecast and the surprise, starts in mid-2026, so treat the scores as a forward signal to test, not a long backtest. History depth follows the plan: 12 months on Starter, 24 on Pro and 10 years on Ultimate.

Which endpoints does a macro forecast need?

Start with /v1/rate-path and /v1/rate-odds for what markets price, /v1/inflation and /v1/jobs with history=true for the paths, /v1/treasury-issuance for supply, and /v1/calendar for the consensus your number has to beat. All of them answer on every plan, with a new print an hour behind below Starter.

Can an AI agent build these with the MCP server?

Yes. Point any MCP client at https://api.helious.io/mcp and the same data arrives as 25 tools, from get_market_context and get_rate_odds to get_inflation, get_jobs and get_auctions. Each answer opens with a sentence the agent can quote, with the numbers underneath.

How much does the Helious API cost?

Starting is free with no key. A free account key gets 7 days of history and 100 credits a month. Starter is $14.99 a month with live prints and 12 months of history, Pro is $39.99 with every price live and the live stream, and Ultimate is $99 with 10 years of history, no credit cap and commercial use. A data call is 1 credit.