What Macro Forecasts Can You Build with the Helious API and MCP Server?
Forecasts you can check: a Fed path, an inflation path, a payrolls number, a growth nowcast, a view on Treasury supply, and a scorecard that grades the release forecasts. Each one has a baseline to beat. Helious holds three of them: what markets price, what the run rate says and what the consensus expects. It also holds the ruler that scores a release when it prints. In 2026 you can build the forecast in code on the REST API, or have an AI agent draft it over the MCP server with a page to cite for every number. This post lists the six builds, shows what markets priced on 17 November 2026, and grades a naive forecast against the consensus on real prints.
1. What does a forecast need from its data?
A forecast is only useful against a baseline. It needs three of them, and a ruler:
- What markets price.
/v1/rate-oddsgives the odds of a hike or a cut at each Fed meeting./v1/rate-pathgives 16 quarterly SOFR futures and 48 monthly fed funds contracts, each with its rate now and six and twelve months ago. - What the run rate says.
/v1/inflationand/v1/jobsreturn every measure with its short windows worked out, so the recent pace sits beside the year rate. - What the consensus expects.
/v1/calendarcarries the consensus for a coming release once it is set. - The ruler. When a US release that Helious has sized prints, the row carries
sigma: the miss in standard deviations for that release. Your miss and the consensus miss go on one scale.
2. Which macro forecasts can you build?
| Forecast | The baseline it has to beat | Endpoints | MCP tools |
|---|---|---|---|
| Fed path | The odds the fed funds strip prices | /v1/rate-odds, /v1/rate-path | get_rate_odds, get_rate_path, get_fed_roster, get_document_digests |
| Inflation path | The consensus for the next CPI and PCE prints | /v1/inflation?history=true | get_inflation |
| Payrolls | The consensus for the jobs report | /v1/jobs?history=true | get_jobs |
| Growth nowcast | The GDP consensus, and GDPNow itself | /v1/series/gdpnow, /v1/series/retail-sales | get_series, list_series |
| Supply view | The refunding schedule and recent auction demand | /v1/treasury-issuance, /v1/auctions, /v1/yields | get_treasury_issuance, get_auctions, get_yield_closes |
| Scorecard | Your own past forecasts | /v1/calendar, /v1/calendar/history | get_economic_calendar |
3. How do you build a Fed path forecast?
Start from the price, because that is the forecast you are disagreeing with. On 17 November 2026 the fed funds strip priced 93% odds of a 25 basis point hike at the 9 December meeting. Through 15 September 2027 it priced 80.5 basis points of hikes, about 3.2 quarter-point moves, taking the effective rate from 3.88% to 4.68%.
Then look at how the price got there. Each contract on /v1/rate-path carries its own past. The September 2027 SOFR contract priced 4.73% on 17 November. Six months earlier the same contract priced 4.055%, and twelve months earlier 3.15%. The market added 158 basis points to that one quarter in a year. These are traded prices, not forecasts. Your forecast is the gap between them and your view.
For the view, read the committee. get_fed_roster lists who votes and how each member leans. get_document_digests returns FOMC minutes and Fed speeches read end to end, each with a hawkish or dovish lean and quotes checked word for word. The rate path post explains the two futures strips.
4. How do you build an inflation path?
From the run rate. /v1/inflation returns each measure with its year rate and its 1, 3 and 6-month annualised rates, and history=true adds the monthly series. No annualising by hand.
The gap between the windows is the forecast. Core CPI's newest year rate, for September 2026, was 2.57%. Its 3-month annualised rate through September was 3.41%, which is 0.28% a month. Now look at what the consensus did. For the August, September and October prints it expected 0.2% each time. Each printed 0.3%, a surprise of 1.67 sigma three months in a row. Going into the 10 November release the run rate said 0.28 and the consensus said 0.2. It printed 0.3, and the 3-month rate rose to 3.75%.
That is one release, not a method. Core PCE pointed the other way through September: 2.90% annualised over three months against 3.12% over the year. A path built on one measure is a guess. The inflation tracker post covers the other measures.
5. How do you grade a forecast against the consensus?
With the consensus record. For each past print /v1/calendar/history returns the consensus as it stood, the first actual, the previous and the revised prior, with the surprise sized. This loop scores any rule against it. The rule here is the simplest one there is: next month equals last month.
import requests
API = "https://api.helious.io"
H = {"Authorization": "Bearer hel_your_key_here"}
def data(path, **params):
r = requests.get(API + path, params=params, headers=H, timeout=15)
r.raise_for_status()
return r.json()["data"]
rows = data("/v1/calendar/history", event="core-cpi", limit=8)["rows"]
rows = [r for r in rows
if None not in (r["consensus"], r["actual"], r["previous"])]
mine = cons = 0.0
for r in rows:
naive = r["previous"] # your model's number goes here
mine += abs(naive - r["actual"])
cons += abs(r["consensus"] - r["actual"])
print(r["period"], "consensus", r["consensus"], "naive", naive,
"actual", r["actual"], (r["surprise"] or {}).get("label"))
n = len(rows)
print(f"mean miss: naive {mine / n:.2f}, consensus {cons / n:.2f}")
Run on the eight newest core CPI rows, March to October 2026, the last line reads mean miss: naive 0.11, consensus 0.10. The consensus beat "same as last month" by a hundredth of a point. So the bar is the consensus, at 0.10. A model that cannot beat even the naive rule on this loop is not ready for the next print.
Two things to know before you run it. The record needs a plan with history. With no key rows comes back empty. And a plan decides how far back the loop reads: 24 months on Pro, 10 years on Ultimate. Eight prints prove nothing. Ten years of them is a test.
6. How do you forecast payrolls and growth?
Payrolls. /v1/jobs splits the headline into private and government, and into sectors that sum to it exactly. In October 2026 the economy added 165,000 jobs. The 3-month average was 137,000 a month, the 6-month 82,500 and the 12-month about 74,000. A forecast starts from which of those paces you believe. Weekly jobless claims, ADP and JOLTS ride in the same answer, and history=true adds each monthly series. The jobs tracker post walks through the sectors.
Growth. /v1/series/gdpnow tracks the quarter in progress, and Helious has captured its revisions since mid-2026. The third-quarter nowcast stood at 6.2% on 3 August and at 3.3% by 28 October. On 17 November the fourth quarter was tracking 3.4%, down from 3.5%.
7. How do you add Treasury supply?
/v1/treasury-issuance separates net new borrowing from gross issuance. In October 2026 the Treasury sold $2,977 billion of marketable debt, and most of it refinanced debt coming due. Net new borrowing was $309 billion. The cash balance at the Fed ended the month at $952 billion, and 37.9% of the last year's net borrowing was raised in bills. The answer also carries the refunding schedule ahead: the next one is February 2027.
Pair it with demand. /v1/auctions shows how each sale was taken down, and /v1/yields gives the 17:00 New York closes as a daily series to forecast against.
8. Can an AI agent write the forecast over the MCP server?
It can draft it. Connect Claude, ChatGPT or any MCP client to https://api.helious.io/mcp and ask for a forecast note on the next CPI print with the market pricing, the run rates and the consensus. The agent can start with get_build_plan, which draws no credit and returns the tools in order. Asked on 17 November for a CPI forecast model run weekly, it answered that one pass is 8 credits, about 32 a month.
Every tool opens with a sentence the agent can quote and names the Helious page to cite, so the note carries its sources. The judgement is still yours. An agent will state what is priced and what the run rate is. Where your number sits against them is the forecast. The AI setup post covers each client.
9. What are the limits?
- The consensus can be unset. A calendar row can carry no forecast until a few days before the print. Check
forecastfor null before you grade. - Some forecasts are implied. A High-impact year-over-year inflation row can carry a forecast Helious worked from the month-over-month consensus, marked
forecast_implied: true. Leave those rows out of a scorecard. - History follows the plan. None on a free key, 24 months on Pro, 10 years on Ultimate. More than 24 months is an Ultimate job.
- Two records, two uses. Helious's own captured prints start in mid-2026, each with the forecast frozen at the print and never rewritten. The consensus record reaches as far back as your plan reads.
- The depth is US. The calendar and the consensus record also cover the euro area, the UK, Germany and Japan. The inflation, jobs and rates boards are US only.
10. What does it cost, and where do I start?
A forecast runs on a slow clock, so it is cheap. One pass of the full recipe is 8 calls: about 32 credits a month run weekly, about 240 run daily. Pro is $39.99 a month with 3,000 credits and 24 months of history. Ultimate is $99 a month with no credit cap and 10 years of history, the plan for a model trained across rate cycles.
Start with no account: curl "https://api.helious.io/v1/rate-odds" returns what the market prices for every Fed meeting. Then open the macro forecast recipe. The other two posts in this set cover the macro systems and the trading algorithms built on the same data.