Read Helious from your own code

Everything the Helious terminal shows, you can also pull as data: Treasury yields and the curve, every economic release the moment it prints, auction results, the currency and volatility boards, and the news feed. Use it from a script, a spreadsheet, or an AI agent. The first call is free and needs no account.

The API is read-only and covers US rates, economic data and market news, with an MCP server alongside it for AI agents. The bar for using it is one web request, so it suits a trader with a script, an analyst with a spreadsheet, a developer building a product, and an agent working on its own.

It costs nothing to start. With no key at all you get 1 day of history and the news an hour behind. The first call is about ten seconds of work: paste one line into a terminal and read what comes back. Paid plans take the news live and open the market prices, from $14.99 a month. Pro and Ultimate also include Ask Helious, the assistant inside the terminal, with a monthly credit allowance.

What you get

The same numbers the desk publishes, in a shape a machine can read.

What you can read

There is one base address for everything, https://api.helious.io, and every call is a plain GET, so you can test any of them in a browser tab. Answers come back as JSON, apart from a handful of addresses built for other tools: the spreadsheet downloads, which return a CSV sample of recent rows, and the news feed at /api/seo/feed.xml, which returns RSS.

What makes it different

Most market APIs hand you a wall of numbers and leave the reading to you. Every Helious answer arrives with the finished sentence first, then the raw data underneath. So a spreadsheet gets its numbers, and a person or an agent gets the point of them without doing the maths again.

Your first call

There is no account to make and no key to send. Paste the line below and run it.

Run it now

Ask for this week's economic calendar:

curl "https://api.helious.io/v1/calendar?days_ahead=7"

import requests

r = requests.get("https://api.helious.io/v1/calendar?days_ahead=7", timeout=15)
print(r.json()["summary"])

const r = await fetch("https://api.helious.io/v1/calendar?days_ahead=7");
const body = await r.json();
console.log(body.summary);

=IMPORTDATA("https://api.helious.io/api/seo/csv/series/cpi")

The spreadsheet tab uses a CSV address instead, because spreadsheets read tables better than they read JSON. There is a CSV file for every economic series and every auction tenor, each holding the recent rows as a free sample. The full history comes through the API, where depth follows your plan. See files for machines.

What comes back

Every /v1 answer has the same four parts, always in this order:

{
  "summary": "2s10s is 54.4bp.",
  "source": {
    "name": "Helious",
    "url": "https://helious.io/rates",
    "cite_as": "Helious, https://helious.io/rates"
  },
  "data": {
    "curve": { "spread_level_bps": 112.9, "segments": [ ... ] },
    "spreads": [ { "key": "2s10s", "level_bps": 54.4 } ],
    "quotes": { "^TNX": { "price": 4.28, "change": 0.03 } }
  },
  "meta": {
    "tier": "pro",
    "as_of": "2026-08-17T23:01:56Z",
    "history_days": 730,
    "delay_sec": 0
  }
}

Build against data and show summary. Both are stable, and both look the same on every plan, so nothing in your code changes when you add a key later.

On plans without market prices, the price addresses still answer 200 in this same shape: data carries the upgrade steps instead of the numbers. So you can wire up every endpoint with no key at all, and the numbers arrive the minute a plan does.

Good first calls

Plans and limits

Five plans. Moving up changes how much you get, never the code you write.

What each plan gets

Every plan comes with credits, and every data call takes one. With no key you share 30 calls a minute and 50 credits a month with everyone else calling from the same network address. A free key of your own gets 60 a minute and 100 credits a month: enough to build and test against every endpoint and every board. Starter has 1,500 credits a month, Pro 3,000, and Ultimate has no cap. Pay for the year and every paid plan is 25% off: $135, $360 or $891. Pro and Ultimate both run the live stream. Ultimate is the commercial plan: it allows redistribution and holds more live stream connections. For anything beyond it, email support@helious.news.

What the plan changes

The plan you are on changes four things: how far back you can look, how fresh the data is, how many credits you have a month, and how fast you may ask. Nothing else changes. Every plan calls the same addresses and gets the same shape of answer, so upgrading is only ever adding a key.

Every board is open on every key. Sample gets no prices at all: the price addresses answer in their normal shape, with the steps to a free key where the numbers would be. Free, Squawk and Starter get every price board 60 minutes behind for 1 credit a call, and live for 5. Starter also takes news and economic prints live. Pro and Ultimate take every price live for 1 credit: yields, commodities, equities, FX, volatility and correlations, on these addresses and on the live stream.

Credits

One wallet pays for everything your account does, and the rules are short. A data call on any /v1 address or any MCP tool costs 1 credit. A typed Ask Helious question in the terminal costs 10. On Free, Squawk and Starter the data arrives an hour behind, and the same call answered live costs 5 (how to ask for it). Reading /v1/me or /v1/access, the MCP handshake, get_access_info and list_series cost nothing, and neither does any error, any 429 or any keyless wall: you pay for data, never for being refused. Every answer carries X-Credits-Charged and X-Credits-Remaining headers and the same two numbers in meta. Plan credits come back each period. Credits you buy in a pack never expire and are spent after the plan's. Credits buy usage; your plan sets how fresh the data is, and a live answer on a free key is 5 credits. The whole tariff, with worked examples, is at helious.io/usage.

Not on Pro? Ask for one call live: fresh=1

On Free, Squawk and Starter every answer is 60 minutes behind. When one call has to be current, say so on the request. Over REST, add ?fresh=1 to the address. Over MCP, put "fresh": true in the tool's arguments. That one call answers live, news, prints, auctions, boards and prices at the live instant, for 5 credits instead of 1. The next call without the flag is an hour behind again, for 1.

curl -H "Authorization: Bearer hel_..." "https://api.helious.io/v1/rates?fresh=1"

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "get_rates_and_curve", "arguments": {"fresh": true}}}

The answer tells you which view you got. A live answer's citation line reads "This is live data", its meta.delay_sec is 0 and its meta.fresh is true. A held answer says how far behind it is, and meta.live_view says how to get it live. 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. On Pro and Ultimate every answer is live already, so the flag is accepted and costs nothing extra. Without a key there is no flag: the price addresses answer with the steps to a free key.

How fast you may ask

The count resets on the clock minute. Go over and the call returns 429 with a Retry-After header holding the seconds left in that minute. Wait that long and carry on. Most things here update on a schedule, not continuously, so polling faster than the data changes only spends your budget.

Get a key

Three steps, about a minute, no card needed for the free plan.

Make the key

1. Create a free account at helious.io and verify your email.
2. In the terminal, open My account (the button at the top right), then the API keys tab.
3. Name the key after whatever will use it, press Create key, and copy it.

Send the key

Every key starts with hel_. Send it as a header, either way round:

Authorization: Bearer hel_your_key_here

X-Api-Key: hel_your_key_here

A full call with the key in place:

curl -H "Authorization: Bearer hel_your_key_here" \
  "https://api.helious.io/v1/feed?limit=5"

The same key works on the REST addresses and on the MCP server, so an agent behaves the same however it connects. A value that does not start with hel_ is ignored and you are served as if you sent nothing.

One key each

You can hold five live keys per account. Give each agent, script or product its own, named after itself. Then you can switch one off without stopping the rest, and the usage column on the keys screen tells you which one is doing the calling. Revoking takes effect within a minute.

Subscribing upgrades the keys you already have. The account carries the plan, not the key, so you never have to reissue anything. That works in reverse too: if a subscription lapses, the keys drop back to the free plan within a minute and keep working.

When a call fails

Three things go wrong in practice, and each one says what to do.

The shape of an error

Errors are JSON with a single error object holding a short code and a message written for a person to read:

{
  "error": {
    "code": "rate_limited",
    "message": "You are over 30 requests a minute. Wait 24 seconds and try again. This free budget is shared by everyone calling from your network address. A free account key gets a budget of its own: GET /v1/access has the steps.",
    "upgrade_url": "https://helious.io/"
  }
}

Branch on code, and show message to whoever is watching. If the message tells you what to do, that text is the instruction, not the status number on its own.

Too many calls: 429

Two limits share the status, and code tells them apart. rate_limited means you are over your calls for this minute: the Retry-After header is the rest of the minute, so the wait is short. out_of_credits means the wallet cannot pay for this call. Nothing is charged for a refusal. The body says what to do: credits_left, resets_on (the date the plan's credits come back), retry_after_seconds, next_step (one sentence to relay), packs (code, credits and price of each pack), topup_url, upgrade_url and, on Free, Squawk and Starter, fresh_costs, so a refused fresh=1 call can say why five credits were needed. There are two ways on, and the person who owns the key chooses: a pack, a one-off charge that never expires, or a plan with more credits every month. Either lands on the key within a minute. On the delayed stream each minute's snapshot takes one credit on Free and with no key, and the socket closes with the same error when they are spent; a paid plan's stream takes none. /v1/access and /v1/me still answer, so an empty wallet never hides the page that explains it. Ultimate has no credit cap. Honour the header in both cases.

A key that does not work: 401

The key is unknown or was revoked. This is deliberately not silent: dropping the key and carrying on as an anonymous caller would hide a broken setup from the person who owns it. Stop, and tell them to check their keys.

Something you asked for does not exist: 400

A value you sent is not one we know, for example a feed category that does not exist. The message lists what you may pick from, so the reply itself tells you how to fix the call. Everything else is forgiving: an unknown query parameter is ignored rather than refused, and a since date older than your plan allows is pulled forward to the earliest date you may see, with meta saying so.

Use it with an AI agent

Your agent can read the whole desk from a single address.

Point it at one address

Claude, Cursor and other AI tools speak MCP. Give yours this address and the data arrives as tools, with no glue code from you:

https://api.helious.io/mcp

claude mcp add --transport http helious https://api.helious.io/mcp

Click-by-click steps, including a one-click install for Cursor, are on the AI setup page.

What the agent can ask for

The tools, named for what they answer:

Agents can also read the sign-in guide themselves. It tells them not to try to make an account, and to send their owner here for a key instead.

Worked examples

Four questions people ask, and the call that answers each.

Is the curve steepening or flattening?

curl "https://api.helious.io/v1/curve?limit=5"

While cash Treasuries are trading and the curve is moving, the answer names one of four regimes: bull steepener, bull flattener, bear steepener or bear flattener. It says when it flipped and what it flipped from. Outside those hours, or when both ends sit still, it returns stable instead, and the read line explains what you are looking at. The list underneath is every earlier flip, as far back as your plan allows. The curve is market data: this call answers with numbers on the paid plans, 60 minutes behind on Starter and live on Pro and Ultimate.

What prints this week?

curl "https://api.helious.io/v1/calendar?days_ahead=7&country=US"

Scheduled releases with the forecast and the previous value, plus Fed speakers and auction times. Once something prints, the same row carries the actual and how big a surprise it was. Drop country to see everywhere, or set it to EU, GB or JP.

How did the last few Treasury auctions go?

curl "https://api.helious.io/v1/auctions?limit=3"

Each auction comes with the high yield, bid to cover and the buyer split, plus how that compares with the last twelve of the same tenor, so you can judge a single sale without pulling the history yourself. Notes and bonds also carry the tail against the pre-sale yield. Bills are sold without a pre-sale market, so they never have one.

Where is inflation now?

curl https://api.helious.io/v1/series/cpi

The latest print, what was expected, the size of the surprise, and the run of prints behind it. Use /v1/series first to see the short name of every number we track.

Rules of the road

Cache anything you fetch twice, name yourself in the User-Agent header, and credit Helious.

Cache what you can

Most of this moves on a schedule. The calendar changes a few times a day, auctions land at known times, and daily closes are fixed once the session ends. Cache anything you ask for twice, and your credits will go much further than you expect.

Say who you are

Send a real User-Agent that names your product and gives us a way to reach you. If something you build starts misbehaving, that header is how we tell you instead of blocking you.

Credit Helious

The curve regime, the surprise scores and the auction tails are measured here, not republished from somewhere else, so there is no upstream source to point at instead. Every answer carries a source.cite_as string ready to paste. Our robots.txt grants search, AI input and AI training openly. Attribution is what we ask for in return.

Every address

They are all GET requests to https://api.helious.io, and they all answer with no key. The /v1 addresses follow your plan for freshness, history and market data. The /api addresses are the same ones the website itself reads, so they are open to everyone on every plan.

Your key

Ask the API who you are and what you are allowed to see.

Rates and curve

US Treasury yields and the curve are market data: Sample and Free get the upgrade steps instead of numbers, Starter gets them 60 minutes behind, Pro and Ultimate get them live. History follows your plan's window. The two Fed pricing addresses at the bottom are the exception and answer on every plan, for the reason each row gives.

Boards

Scoreboards we rebuild on a schedule. Each keeps its past readings, so you can chart the trend. The price boards are market data and answer with numbers on Pro and Ultimate; Hormuz transits are ship counts, not prices, and answer on every plan.

Economic data

What is coming, what landed, and how far off the forecast it was. On Sample and Free, the /v1 addresses and /api/calendar hold a print for 60 minutes after it lands, as the feed does: a calendar or series row shows status: delayed and reveal_at instead of the actual, and the inflation and jobs boards carry held_until while the new print waits. Every paid plan sees it the moment it prints.

Those last three answer with the latest reading on every plan, so you can wire them up and test before anyone pays. Add history=true and the monthly series behind each measure follows your plan's window instead: 7 days on a free key, 12 months on Starter, 24 months on Pro, 10 years on Ultimate. You always get the newest month back, and a plan_limit block tells you which month the window reached and what opens the rest.

Treasury auctions

Every US Treasury sale: the clearing yield, the demand, and who took it down.

News and feed

What Helious itself published. Live from Starter up, an hour behind on Sample and Free.

The Fed and reference

Who decides, when they meet, and what the terms mean.

The stream

One WebSocket on every plan. Delayed below Pro; live on Pro and Ultimate.

Connect

Every plan can hold the socket open, even with no key at all. Point your client at:

wss://api.helious.io/v1/stream

Send the same hel_ key you use everywhere else, as a header, never in the address: a key in a query string lands in every proxy log on the path.

Authorization: Bearer hel_your_key_here

What the plan changes is the clock, never the shapes. Below Pro the socket runs the delayed lane: one snapshot a minute, with prices and the NASDAQ-100 board 60 minutes behind and news on your plan's own delay. 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. The hello message says which lane you are on, and an integration built on the delayed lane keeps working untouched the minute the key upgrades.

What it sends

The first message is a hello naming your plan and lane. Then a snapshot of the feed, the price board, the NASDAQ-100 board and the daily closes, so the stream is useful from the first byte. After that, messages arrive as things happen on the live lane, and once a minute on the delayed lane:

Every message is one JSON object with a type field. Send the text ping any time and you get {"type": "pong"} back. The socket re-checks your key about every five minutes, so a revoked or changed key stops streaming within that window.

Try a call in the browser

The reference below is live. It makes real calls and shows the real answers, with no code from you.

How to run one

Open any row, press Try it out, then Execute. The real answer appears underneath, along with the exact curl command for the same call, ready to paste.

What Authorize does

Press Authorize at the top of the reference and paste a key to run these calls on your own plan instead of the no-key one. Nothing is sent anywhere except to the API, and the key stays in your browser.

Files for machines

Everything above, in forms other software can read on its own.

The spec

Tables and feeds

There is a CSV for every economic series and every auction tenor, plus the auction tails dataset, all of them shaped to drop into a spreadsheet. Each holds the recent rows as a free sample and ends with a line naming where the depth lives: the full history comes through the API, where the window follows your plan. An RSS feed carries the newest posts for anyone who would rather read them than parse them. All of it is free on every plan, with no key.

Need a hand

Every one of these goes to a person, not a queue.

Ask us

Email support@helious.news with what you called and what came back. If something looks wrong in the data, say so plainly and we will check it and correct it.

Learn what the numbers mean

Methodology covers how releases are scored and where each number comes from. The glossary defines the terms with live worked examples, and the guides walk through reading auctions, data and the curve. The help centre covers the terminal itself.