Read Helious from your own code

Everything the Helious terminal shows, you can also pull as data: live Treasury yields, 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.

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 CSV, 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#

No account, no key, no sign-up form. Paste and run.

Run it now

Ask for the Treasury curve:

curl https://api.helious.io/v1/rates

import requests

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

const r = await fetch("https://api.helious.io/v1/rates");
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. 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": "keyless",
    "as_of": "2026-08-17T23:01:56Z",
    "history_days": 7,
    "delay_sec": 3600
  }
}

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.

Good first calls

Plans and limits#

Four plans. They change how much you get, never what you write.

The ladder

With no key you share a budget of 30 calls a minute with the other people calling from the same place. A key of your own gets its own budget, which is the main reason to make one even while you stay on the free plan. For commercial terms above the subscriber plan, email [email protected].

What changes, and what never does

The plan changes three things: how fresh the moving numbers are, how far back you can look, and how fast you may ask. That is all. Every plan calls the same addresses and gets the same shape of answer, so upgrading is only ever adding a key.

The delay covers anything that moves during the session: the news feed, the yields board, the Treasury curve and the NASDAQ-100 board. Daily closes and everything historical are identical on every plan, including with no key at all.

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 simply 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. 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

You are over your budget for this minute. The response carries a Retry-After header in seconds. Honour it. It is only ever the remainder of the current minute, so the wait is short.

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 quietly pulled forward to the earliest date you may see, with meta saying so.

Use it with an AI agent#

One address turns the whole desk into tools your agent already knows how to use.

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

For Claude Code, that is one command:

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

Then just ask it what the curve is doing. To use your own plan, add the same Authorization header your scripts use. With no key the agent still works, on the no-key plan.

What the agent can ask for

Seventeen 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 actually 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 actually 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.

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#

Short version: cache it, say who you are, and credit us.

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 budget will feel much larger than it is.

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 rather than simply 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#

All of them are GET, all of them are on https://api.helious.io, and all of them work with no key. The /v1 addresses follow your plan for freshness and history. 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

Live with a subscription, one hour behind otherwise. Closes and history are the same on every plan.

Boards

Scoreboards we rebuild on a schedule. Each keeps its past readings, so you can chart the trend.

Economic data

What is coming, what landed, and how far off the forecast it was.

Treasury auctions

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

News and feed

What Helious itself published. Delayed an hour without a subscription.

The Fed and reference

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

Try a call in the browser#

The reference below is live. Real calls, real answers, no code.

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

For spreadsheets there is a CSV for every economic series and every auction tenor, plus the whole auction tails dataset. For readers there is an RSS feed of the newest posts. Both are free on every plan, with no key.

Need a hand#

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

Ask us

Email [email protected] 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.