Getting Started
MarketDX is a financial news → impact graph. Every article in our system is enriched with which assets and megatrends it moves, which direction, why it matters, and how strongly it ripples through connected sectors and companies.
That's different from a plain news feed. When NVIDIA posts earnings, we don't just return the headline — we tell you that it's a pos impact on demand, that NVIDIA is a leader with core exposure, and that the ripple hits Advanced Packaging names like ASE and Amkor three nodes away in the supply chain.
What developers actually build with this
Here's a sampling of real questions MarketDX answers out of the box:
| Question | How |
|---|---|
| "Show me US large-cap tech stocks with a golden cross AND ROE > 20%" | POST /v1/screen with a TA + fundamental leg |
| "What news is hitting NVDA right now, and which aspect?" | GET /v1/stocks/NVDA.US/news |
| "Find cheap semiconductor names in Asia — low P/E, still above 200-day MA" | POST /v1/screen with country + GICS + TA + fundamental |
| "High-margin, low-debt stocks that sold off hard and are now oversold (RSI < 30)" | POST /v1/screen — fundamental + RSI signal |
| "How is the AI theme doing this month — winners, losers, key storylines?" | GET /v1/megatrends/{id}/summary |
| "Which commodity futures has the most stretched / crowded positioning?" | GET /v1/positioning/extremes |
| "Is Apple expensive right now compared to Microsoft and TSMC?" | GET /v1/financials/compare?ids=AAPL,MSFT,2330.TW |
| "What's moving in semiconductors this week? Biggest winners and losers by news impact." | GET /v1/news scoped to the Semiconductors megatrend |
| "Any stocks coiling up in a volatility squeeze before a big move?" | POST /v1/screen with ttm_squeeze TA pattern |
| "Which stocks did the options market just flip from fearful to confident on?" | POST /v1/screen with fear_to_confidence options leg |
1 · Get an API key
Sign in to the MarketDX Console, go to API Keys, and create a key. It looks like avn_live_… and is shown only once — store it in a password manager.
:::info Plan limits Every key has access to all endpoints your plan allows. There is no per-endpoint key scoping. See Credits & rate limits below. :::
2 · Base URL and authentication
Every request goes to:
https://api.marketdx.lab.ai/v1
Pass your key as a Bearer token in the Authorization header — no other auth mechanism is supported.
- curl
- Python
- Node.js
curl -H "Authorization: Bearer avn_live_YOUR_KEY" \
"https://api.marketdx.lab.ai/v1/stocks/NVDA.US/news?limit=3"
import requests
BASE = "https://api.marketdx.lab.ai/v1"
KEY = "avn_live_YOUR_KEY"
HDR = {"Authorization": f"Bearer {KEY}"}
r = requests.get(f"{BASE}/stocks/NVDA.US/news", headers=HDR, params={"limit": 3})
r.raise_for_status()
articles = r.json()["results"]
const BASE = "https://api.marketdx.lab.ai/v1";
const KEY = "avn_live_YOUR_KEY";
const res = await fetch(`${BASE}/stocks/NVDA.US/news?limit=3`, {
headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) throw new Error(await res.text());
const { results } = await res.json();
3 · What a response looks like
Here's a single article from /v1/stocks/NVDA.US/news:
{
"cs_job_id": "cs_abc123",
"title": "NVIDIA Q2 data-center revenue hits $26.3B, up 154% YoY",
"published": "2026-08-27T14:30:00Z",
"source": "reuters",
"impact_score": 5,
"direction": "pos",
"aspect": "demand",
"brief_text": "NVIDIA's Q2 data-center revenue beat consensus by 12%, driven by accelerating inference demand from hyperscalers.",
"tagged": true,
"role": "leader",
"exposure": "core",
"dup_count": 18
}
Every article has two layers of information:
Article fields (always present)
| Field | Type | What it means |
|---|---|---|
cs_job_id | string | Stable, unique article ID across all endpoints. |
title | string | Original headline. |
published | ISO 8601 | Publication time (UTC). |
source | string | Outlet — reuters, nikkei, yahoo_jp, etc. |
impact_score | 1–5 | Newsworthiness. 5 = market-moving, 1 = low signal. Filter high-signal-only with ?min_impact=4. |
brief_text | string | One-sentence AI summary. Pass ?lang=th or ?lang=ja to translate. |
news_types | string[] | Category tags. Full list at GET /v1/news/types. |
dup_count | int | How many outlets ran the same story (deduplicated into one row by default). Pass ?collapse=false for the raw feed. |
Impact fields (what makes MarketDX different)
These fields explain what the news means for the asset — not just that it happened.
| Field | Type | What it means |
|---|---|---|
direction | pos | neg | ambiguous | Whether the news is bullish, bearish, or unclear for this asset. |
aspect | string | Which dimension of the business is hit. One of: demand · technology · capital · competition · regulation · supply · pricing · geopolitics. Filter with ?aspect=regulation to see only regulatory hits. |
magnitude | 1 | 2 | How broad the impact is. 1 = affects one company/narrow. 2 = cohort-wide or systemic. |
tagged | bool | true = the article names this company directly. false = the company is hit indirectly through a theme it belongs to. |
role | string | The company's part in the story: leader · enabler · adopter · infrastructure_provider · beneficiary. |
exposure | core | secondary | core = pure-play in the affected trend. secondary = peripheral exposure. |
rationale | string | One-line explanation of why this article maps to this asset — the "because". |
4 · Ticker format
MarketDX uses its own ticker notation. Don't guess exchange suffixes for non-US names — use GET /v1/stocks/resolve to look up the right ticker first.
| Asset class | Format | Examples |
|---|---|---|
| US stocks & ETFs | bare symbol | AAPL, NVDA, SPY, QQQ |
| Non-US stocks | SYMBOL.EXCHANGE | 7203.JP (Toyota), ADVANC.BK (Thailand), 005930.KO (Samsung) |
| Crypto | SYMBOL | BTC, ETH, SOL |
| Commodities | SYMBOL.COMM | GOLD.COMM, COPPER.COMM, OIL.COMM, CARBON_EU.COMM |
| FX pairs | PAIR.FX | USDJPY.FX, EURUSD.FX |
| Government bond yields | CC-TENOR.GB | US-10Y.GB, DE-2Y.GB, JP-10Y.GB |
| Money-market rates | TOKEN.MM | SOFR.MM, EFFR.MM, EURIBOR3M.MM |
:::warning Korea uses .KO, not .KS
005930.KS returns a 404. The correct ticker is 005930.KO. When in doubt, call GET /v1/stocks/resolve?q=Samsung — it returns the exact ticker for any name.
:::
:::tip Commodities have two contracts for some metals
Gold and copper have both an LME/USD contract (GOLD.COMM) and an onshore-China/CNY contract (GOLD_CN.COMM). Palm oil has PALMOIL.COMM (USD) and PALMOIL_MY.COMM (Bursa MYR). Use the one that matches your market context.
:::
5 · Credits & rate limits
Every response carries two headers so you can track spend per call:
X-Credits-Charged: 5
X-RateLimit-Remaining: 55
Credits reset at 00:00 UTC daily.
| Plan | Credits / day | Requests / min |
|---|---|---|
| Free | 200 | 10 |
| Personal | 20,000 | 60 |
| Advanced | 100,000 | 120 |
| Redistribution | Unlimited | 600 |
What costs credits:
| Endpoint type | Cost |
|---|---|
News feeds (/v1/news, /v1/stocks/{id}/news, etc.) | 1 credit per article returned — page size IS your cost |
Screener (POST /v1/screen) | 5 credits flat per call |
| Stock prices, financials, megatrend data | 1 credit per call |
Resolvers (/v1/stocks/resolve, /v1/ta/find-signal, /v1/megatrends, etc.) | Free — 0 credits |
:::tip Managing news feed spend
Set ?limit=20 while building and only raise it in production. On a news feed, limit=200 costs 200 credits — the same as your entire Free daily quota in one call.
:::
Going over your rate limit returns 429 with a Retry-After header. Running out of credits returns 402.
6 · Pagination
Every list endpoint — news feeds, stock lists, search results — supports the same three controls:
| Param | Default | What it does |
|---|---|---|
limit | 50 | Page size. Range: 1–1,000. |
offset | 0 | Rows to skip. Increase to page forward. |
all | false | Returns the full matching set (up to 5,000 rows), ignoring limit/offset. Costs 1 credit per row on news. |
Every response echoes these params back and adds has_more: true when there's another page.
- curl
- Python
- Node.js
# Page 1 — rows 1–50
curl -H "Authorization: Bearer avn_live_xxx" \
"https://api.marketdx.lab.ai/v1/news?megatrend=10000000&limit=50"
# → has_more: true
# Page 2 — rows 51–100
curl -H "Authorization: Bearer avn_live_xxx" \
"https://api.marketdx.lab.ai/v1/news?megatrend=10000000&limit=50&offset=50"
articles = []
offset = 0
while True:
r = requests.get(
f"{BASE}/news",
headers=HDR,
params={"megatrend": 10000000, "limit": 50, "offset": offset},
)
page = r.json()
articles.extend(page["results"])
if not page.get("has_more"):
break
offset += 50
const articles = [];
let offset = 0;
while (true) {
const res = await fetch(
`${BASE}/news?megatrend=10000000&limit=50&offset=${offset}`,
{ headers: { Authorization: `Bearer ${KEY}` } }
);
const page = await res.json();
articles.push(...page.results);
if (!page.has_more) break;
offset += 50;
}