Checking your account...
Create your free API key
Every FXNewsBias account can hold an API key, no card required. Free keys allow 25 requests a day and serve the previous 3-hour cycle. Pro keys are real-time at 1,000 a day. Sign in and the key panel appears right here.
Free tier is for building, testing and non-commercial projects, with attribution. It ships in every response, so there is nothing to guess.
// what you get back { "schema": "fxnb.sentiment.v1", "generated_at": "2026-08-21T09:00:12Z", "data": [ { "currency": "USD", "score": 72, "bias": "Bullish" }, { "currency": "EUR", "score": 42, "bias": "Bearish" }, ... 6 more ] }
Create your API key
One key per account, created instantly. You will see it once, right here, the moment it is created. We only ever store a fingerprint of it, so it cannot be shown again afterwards.
Your key will be on the free tier: 25 requests a day on the sentiment endpoint, serving the previous 3-hour cycle. Non-commercial use with attribution. Want real-time data, 1,000 requests a day, the session scorecard and gold (XAU/USD)? Pro starts with a 7-day free trial plans.
This is the only time the key is shown. We store a fingerprint, not the key itself, so we genuinely cannot show it to you again. Lost it? Regenerate below, which replaces it and kills the old one.
This is a free tier key: 25 requests a day, sentiment endpoint, data one 3-hour cycle behind (each response says "delayed": true). Non-commercial use with attribution. Upgrade to Pro for real-time data, 1,000 requests a day, the session scorecard and gold (XAU/USD); your key upgrades automatically.
Endpoints
Five GET endpoints, plus four Markets (Pro) endpoints for gold, silver, oil, crypto and the US indices further down, all authenticated with the same key. Base URL https://fxnewsbias.com. Machine-readable spec: openapi.json, OpenAPI 3.1, import it straight into Postman, Insomnia or a client generator.
currency, from, to, page with limit and offsetFree keys serve forward data: the current read, one 3-hour cycle behind. Everything else is on Pro, which removes the delay, raises the allowance to 1,000 a day and opens both history endpoints, the live session bias and the gold markets endpoints. The scorecard history returns settled reads only, so every row has a real outcome attached. Pro starts with a 7-day free trial, see the plans.See the plans.
Quickstart
Bearer header only. Keys are never accepted in the URL or query string.
curl -H "Authorization: Bearer $FXNB_KEY" \
https://fxnewsbias.com/api/v1/sentiment
Python
Official client, MIT licensed, no required dependencies.
pip install fxnewsbias
from fxnewsbias import Client
fx = Client("fxnb_live_...")
# the whole point: a yes or no on the pair you are about to trade
fx.sentiment().favours("AUD/USD") # 'long', 'short', or None
fx.sentiment().spread("AUD/USD") # 13 (AUD 68 - USD 55)
The scores move every few hours, so follow() waits for the next
one instead of polling on a timer. A 15-minute loop spends 96 calls a day; this spends about 8.
for s in fx.follow():
print(s["AUD"].score) # blocks until the data actually changes
Gold and the other markets, on Pro keys, from fxnewsbias 1.2.0 (pip install -U fxnewsbias; 1.2.1 documents every symbol). Details under Markets (Pro).
m = fx.markets()
gold = m.get("XAU") # None until the first gold read
if gold:
print(gold.score, gold.pair.bias) # e.g. 64 Bullish
Use with AI agents (MCP)
Use FXNewsBias in Claude
FXNewsBias is listed in Claude’s connector directory. Connect it once and ask Claude about the sentiment in your own words, for example “what is the sentiment on the US dollar right now?” or “which currency reads most bearish today?”. No code and no key to copy.
- Open FXNewsBias in Claude’s connector directory and connect it.
- Sign in with your FXNewsBias account (a free account is enough to start).
- Click Allow, then ask Claude.
A free account gives 25 reads a day of the 8 major currencies, one 3-hour update behind. Pro gives live reads, 1,000 a day, with the session bias calls and their record, sentiment history, and gold, silver, oil, crypto and the US indices. Reads in Claude share the daily allowance of your account’s API key.
Connect in ClaudeThe same API is served over the Model Context Protocol, so an AI agent can call it as tools. Two ways in.
Sign in (Claude.ai, Claude Desktop, ChatGPT and other apps that add connectors by URL): in Claude, FXNewsBias is listed in the Claude connector directory, so you can find it in the connector list and connect in one step. In other apps, add a custom connector with the URL https://fxnewsbias.com/mcp. Either way, sign in with your FXNewsBias account when the app asks. No key to copy. The agent gets what your plan gives: free accounts 25 calls a day, one cycle behind; Pro 1,000 a day, live.
With a key (Claude Code, Cursor, Windsurf, VS Code and SDKs): your own key in the header. One tool call is one API call against your daily allowance, same tiers, same data.
claude mcp add --transport http fxnewsbias https://fxnewsbias.com/mcp \
--header "Authorization: Bearer $FXNB_KEY"
Cursor and other clients: add a remote MCP server with the URL https://fxnewsbias.com/mcp, transport http (streamable HTTP), and the header Authorization: Bearer fxnb_live_... (or X-API-Key: fxnb_live_... where the client only offers a plain key header). Then ask the agent, for example, "check the FXNewsBias session bias before London" or "which way is EUR/USD sentiment leaning".
symbol), by date range, pagedRead-only. A free key calling a Pro tool gets the same pro-only answer as the REST endpoint, with the upgrade link, so the agent can tell you what it needs. Errors (missing key, allowance used up, Pro-only) come back as tool results the agent can read, never as a broken connection. No raw prices, as everywhere in the API. The tool descriptions carry the attribution and the not-advice line; keep both wherever the data is shown.
Connected agents
Apps you have signed in through the connector route. Disconnecting revokes every connection; each app will ask you to sign in again.
Response shape
{
"schema": "fxnb.sentiment.v1",
"generated_at": "2026-08-21T09:00:12Z",
"next_update_expected": "2026-08-21T12:00:00Z",
"attribution": {
"required": true,
"text": "Data by FXNewsBias",
"url": "https://fxnewsbias.com"
},
"data": [
{ "currency": "USD", "score": 72, "bias": "Bullish",
"updated_at": "2026-08-21T09:00:00Z" },
... 7 more
]
}
| Field | Contract, frozen. v1 never changes shape |
|---|---|
data | Always exactly 8 rows, ordered USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD |
score | Integer 0 to 100. 50 is the neutral midpoint, higher is bullish news tone, lower is bearish |
bias | Exactly one of Bullish, Bearish, Neutral |
updated_at | ISO-8601 UTC. When the score was computed |
next_update_expected | When the next refresh lands. Sleep until this, then poll once |
delayed | Free-tier responses only: true, alongside delay_hours: 3. The scores are from the previous cycle. Absent on Pro |
Tiers and rate limits
| Free | Pro | |
|---|---|---|
| Price | $0, no card | From $20/month, 7-day free trial |
| Requests per UTC day | 25 | 1,000 |
| Data freshness | Previous 3-hour cycle (3 to 6 hours old) | Current cycle, real-time |
/api/v1/sentiment | Yes, delayed | Yes, real-time |
/api/v1/session-bias | No | Yes |
/api/v1/sentiment/history | No | Yes |
/api/v1/session-bias/history | No | Yes |
/api/v1/markets and its 3 sub-paths (gold) | No | Yes, real-time |
/api/v1/usage | Yes, free of allowance | Yes, free of allowance |
| Use | Non-commercial, with attribution | Commercial use in your own product |
- Both tiers reset at 00:00 UTC. Every response carries
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset - One over the limit returns
429with aRetry-Afterheader - The allowance follows the account, not the key, so regenerating a key does not reset it
- Free responses include
"delayed": true, "delay_hours": 3so the freshness is never ambiguous
Errors
| Status | Body | When |
|---|---|---|
400 | {"error":"bad-from", "message":"..."} | A parameter was rejected. Validated before the allowance is claimed, so a bad request costs you nothing |
401 | {"error":"unauthorized", "message":"..."} | Missing header, malformed header, or a key that is not active. The message says which of the three |
403 | {"error":"pro-only", "message":"..."} | The key is valid but on the free tier, and the endpoint is Pro only: the live session bias or any Markets path. Markets responses also carry an upgrade link. Returned before the allowance is claimed |
404 | {"error":"not-found", "endpoints":[...]} | No endpoint at that path. Paths are exact and take no trailing slash. The body lists the real ones |
405 | {"error":"method-not-allowed"} | Anything but GET |
429 | {"error":"rate-limited","retry_after_seconds":n} | Past your daily limit |
- Branch on
error, never onmessage. The code is part of the frozen contract, the wording is not - Working integration suddenly returning
401? Regenerating a key replaces the previous one. If someone clicked regenerate in the panel, anything still sending the old key stops there. Create a new key and update your integration 502and500are ours and safe to retry.400,401and404will not change on a retry, so fix the request instead
Attribution and terms
- Wherever the data is displayed or republished, keep the attribution "Data by FXNewsBias" linking to
https://fxnewsbias.com. It ships in every response - Free tier is for personal and non-commercial projects. A Pro subscription covers commercial use inside your own product
- No redistribution, resale, or using the data to build a competing sentiment service, on either tier
- One key per account. Sharing a key across separate users or products is not permitted and is detectable
- One key for the life of the account. It upgrades to Pro automatically when your subscription or trial starts, and returns to the free tier when Pro ends. The key string never changes, so your integration keeps working either way, on free limits afterwards
- Questions, higher volume, or a data licence: contact@fxnewsbias.com
Staying current without wasting quota
Scores publish on a fixed 3-hour cycle. Rather than polling blindly, read next_update_expected and come back then. You get the new data within seconds of publication and spend about 8 requests a day. Gold on the Markets endpoints is scored right after the currency cycle, usually one to three minutes after next_update_expected, so poll those about 3 minutes later and retry a minute after that if updated_at has not changed.
import requests, time
from datetime import datetime, timezone
H = {"Authorization": "Bearer " + FXNB_KEY}
while True:
r = requests.get("https://fxnewsbias.com/api/v1/sentiment", headers=H).json()
handle(r["data"])
nxt = datetime.fromisoformat(r["next_update_expected"].replace("Z", "+00:00"))
time.sleep(max(30, (nxt - datetime.now(timezone.utc)).total_seconds() + 20))
Markets (Pro)
Gold (XAU/USD) and the other markets (silver, WTI and Brent crude, Bitcoin, Ether, Solana, XRP, BNB and the US 500, US Tech 100 and Dow 30) are served on their own endpoints, so the sentiment endpoint above keeps exactly 8 currency rows. Same key, same Bearer header, same 1,000-a-day allowance and rate headers as every other call. These paths are Pro only: a free key gets 403 with "error": "pro-only". More instruments will join the same endpoints later, so treat data as a list and never assume its length. The markets covered today are listed on the Markets page; the free XAU/USD label, one cycle delayed, is on the XAU/USD page.
symbol (XAU, XAG, WTI, XBR, BTC, ETH, SOL, XRP, BNB, SPX, NDX, DJI)symbol is required (XAU, XAG, WTI, XBR, BTC, ETH, SOL, XRP, BNB, SPX, NDX or DJI); from, to, limit and offset work as on the sentiment historysymbol is requiredsymbol is required; the pip size is stated in pip_conventioncurl
curl -H "Authorization: Bearer $FXNB_KEY" \
https://fxnewsbias.com/api/v1/markets
curl -H "Authorization: Bearer $FXNB_KEY" \
"https://fxnewsbias.com/api/v1/markets/history?symbol=XAU&from=2026-10-01&limit=100"
Python, with requests
import requests
H = {"Authorization": "Bearer " + FXNB_KEY}
BASE = "https://fxnewsbias.com/api/v1/markets"
r = requests.get(BASE, headers=H)
if r.status_code == 403: # free key: gold is a Pro feature
raise SystemExit(r.json()["message"])
# data is a list that grows, so look gold up by symbol
gold = next((m for m in r.json()["data"]
if m["symbol"] == "XAU"), None)
if gold:
# e.g. 64 Bullish Bullish
print(gold["score"], gold["bias"], gold["pair"]["bias"])
# settled, aligned, contra, aligned_pct, gold only
calls = requests.get(BASE + "/session-bias/history",
headers=H, params={"symbol": "XAU"}).json()
print(calls["summary"])
The official Python client covers the same four endpoints from fxnewsbias 1.2.0: fx.markets(), fx.markets_history("XAU"), fx.market_session_bias("XAU") and fx.market_session_bias_history("XAU"). A free key raises PlanError with the server's message.
Response shape
{
"schema": "fxnb.markets.v1",
"generated_at": "2026-10-05T09:00:14Z",
"next_update_expected": "2026-10-05T12:00:00Z",
"attribution": { ... same object as every response ... },
"data": [
{
"symbol": "XAU", "name": "Gold",
"score": 64, "bias": "Bullish",
"drivers": ["Softer US inflation data lifts rate cut expectations",
"Central bank gold buying continues"],
"updated_at": "2026-10-05T09:00:09Z",
"pair": { "name": "XAU/USD", "quote": "USD",
"quote_score": 51, "gap": 13, "bias": "Bullish" }
}
]
}
Fields
| Field | Meaning |
|---|---|
data | One entry per market. Today it holds gold only. Instruments will be added, so find gold by symbol and never assume a fixed length or position |
symbol, name | XAU and Gold |
score | Integer 0 to 100, gold's own sentiment on the same scale as the currencies. 50 is neutral |
bias | From the score: Bullish at 60 or higher, Bearish at 40 or lower, Neutral in between |
drivers | Up to 3 short phrases naming the catalysts behind the score |
pair.gap | Gold's score minus pair.quote_score, the latest US dollar score. null if no dollar score was available |
pair.bias | Bullish above +10, Bearish below -10, Neutral in between, the same thresholds as every pair on the site. null when gap is |
move_pips | On the session history: 1 pip = $0.10 per ounce, so move_pips is move_usd times 10. Every response there repeats this in pip_convention |
entry_price, result_price | Always null since 10 October 2026, on both session histories. Raw prices are not part of the API; the fields stay so existing code keeps working. Use the move fields for the size and direction |
entry_price_at, result_price_at | On both session histories since 29 October 2026: when the entry and result quotes were captured by the price job, usually a few minutes before entry_time (the call published) and result_time (the call settled). Use these times to reproduce a move against another price feed. null where the time could not be established |
Behaviour
- A free key gets
403{"error":"pro-only","message":"Gold and other markets are a Pro feature.","upgrade":"https://fxnewsbias.com/pricing"}, before any allowance is claimed - A missing or unsupported
symbolis a400{"error":"bad-symbol"}, and a bad date or page parameter gets the same codes as the sentiment history. Both are checked before the allowance is claimed - Each call that passes those checks counts once against the same 1,000-a-day Pro allowance.
/api/v1/usageshows the combined total - Gold is scored every 3 hours, on the same cycle as the currencies. Session calls are published on weekdays for the Asia, London and New York sessions, like the forex scorecard, and are never mixed into the forex scorecard or its hit rate
/api/v1/marketslists only markets that already have a reading, sodatacan be an empty list before a market's first read. Find a market bysymbol, never by position/api/v1/markets/session-biasreturns"data": nulluntil a first call exists. The history endpoints give the start of each gold series incoverage_from- Gold prices used to settle session calls are an hourly reference, indicative and not an official benchmark
Frequently asked questions
What is a forex sentiment API?
A forex sentiment API returns a machine readable measure of how positive or negative published news is for each currency. The FXNewsBias API returns a 0 to 100 score for the 8 major currencies as JSON. Above 50 leans bullish, below 50 leans bearish, and 50 is neutral.
How often is the forex sentiment data updated?
Scores are recomputed every 3 hours on a fixed cycle, eight times a day from 00:00 UTC, seven days a week. Every response carries a next_update_expected timestamp so you can sleep until the next publication instead of polling blindly. See how the scoring works.
Which currencies does the API cover?
USD, EUR, GBP, JPY, AUD, CAD, CHF and NZD. The sentiment endpoint always returns exactly 8 rows in that order, so the shape never changes between calls. Gold (XAU/USD) is served on its own Pro endpoints under /api/v1/markets, so the sentiment endpoint keeps exactly 8 rows. Browse the live currency scores.
Does the API cover gold and the other markets?
Yes, on Pro. /api/v1/markets returns the latest read for every market: gold, silver, WTI and Brent crude, Bitcoin, Ethereum, Solana, XRP, BNB and the US 500, US Tech 100 and Dow 30 (symbols XAU, XAG, WTI, XBR, BTC, ETH, SOL, XRP, BNB, SPX, NDX and DJI), each with its sentiment score, bias, up to three drivers and the read against the US dollar. /api/v1/markets/history serves every 3-hour read of one symbol, /api/v1/markets/session-bias its newest session call and /api/v1/markets/session-bias/history its settled calls with their results. They use the same key and the same 1,000-a-day allowance as every other call. Free keys get a 403 on these paths; each market's bias label is on the website, one cycle delayed.
How much does the forex sentiment API cost?
The free tier costs nothing: 25 requests a day with data one cycle behind, no card required. Real-time access is included with FXNewsBias Pro, from $20 per month billed yearly ($25 on 3 months, $30 monthly), which starts with a 7 day free trial. There is no separate API fee. See what else Pro includes.
Is there a free tier?
Yes. Any signed-in account can create a free key from the panel at the top of this page, no card required. It allows 25 requests a day on the sentiment endpoint and serves the previous 3-hour cycle, so the data is between 3 and 6 hours old. Built for testing, learning and non-commercial projects, with attribution. When you need the current cycle, Pro is real-time.
What is the rate limit?
Free keys: 25 requests per UTC calendar day. Pro: 1,000 per day per account. Both reset at 00:00 UTC. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and going over returns HTTP 429 with a Retry-After header.
Does the API provide historical sentiment data?
Yes, on Pro. /api/v1/sentiment/history serves every 3-hour read since 19 May 2026, and /api/v1/session-bias/history serves the settled session ledger since 6 August 2026 with the move in percent and pips and whether the call aligned, misses included. Both page with limit and offset. Gold history is on /api/v1/markets/history and /api/v1/markets/session-bias/history from the first gold read; each response gives the exact start in coverage_from. Free keys serve the current read only, one cycle behind. Pro includes all of them, with a 7-day free trial, see the plans.
How do I get an API key?
Create a free account, sign in, and the key panel at the top of this page creates one instantly. There is no application form, no waiting list, no card, and no email delivery. The key is shown once at creation because only a fingerprint of it is stored. Subscribing upgrades that same key to Pro automatically, so there is no second key to fetch and nothing to reconfigure.