# News RSS

<figure><img src="/files/LlQRDnz7xW3jnyqF0jNw" alt=""><figcaption></figcaption></figure>

### 1. Overview

News RSS is the real-time stream of individual news produced by NS3's news analysis pipeline (Pipeline A). AI reads every article published across 20+ trusted media outlets, then delivers it with importance classification, structured analysis, related coin mapping, and 16-language translation already completed.

* **Real-time updates:** As soon as news is processed and published on the NS3 platform, it appears in the RSS feed.
* **AI Insight**: Every article includes structured analysis across five sections — Key Point, Market Sentiment, Similar Past Cases, Ripple Effect, and Opportunities & Risks.
* **Latest 100 items**: Each RSS URL returns the most recent 100 news items.
* **16 languages**: All content is delivered simultaneously in 16 languages.
* **20+ trusted media**: Reads from CoinDesk, Cointelegraph, CoinMarketCap, Bloomberg Crypto, Reuters Crypto, Forbes Crypto, Fortune Crypto, The Block, Watcher.Guru, and more.
* **Content filtering**: Sponsored content, editorial-wrapped promotions, affiliate listicles, presale/casino/ICO promotions, and exchange marketing campaigns are filtered and never delivered.

***

### 2. How AI Classification Works

This section explains what data NS3's AI assigns to each news article, and how that data is derived. This is what makes NS3 fundamentally different from traditional news sources.

#### 2.1 Level & newsType

> "Would a crypto market participant NEED to know this today?" → Level 1, 2. \
> "Nice to know but can wait until tomorrow?" → Level 3.\
> "Is there anything to analyze beyond the headline?" → If no, Level 4.\
> "Is this journalism, or promotional noise?" → If noise, Level 5.

Every article is assigned an importance Level (1–5) and a newsType (breaking / important / normal). These two fields are derived from a single classification system.

When classification is uncertain, AI always downgrades by one level. The principle: underestimation is better than overestimation.

<table><thead><tr><th width="69.79998779296875">Level</th><th width="110.39996337890625">newsType</th><th width="314.599853515625">Meaning</th><th>Insight</th></tr></thead><tbody><tr><td>1</td><td>breaking</td><td>Event that can move the entire market immediately</td><td>Full Insight (5 sections)</td></tr><tr><td>2</td><td>important</td><td>Event that can realistically change market rules, access, or liquidity expectations</td><td>Full Insight (5 sections)</td></tr><tr><td>3</td><td>normal</td><td>General crypto news</td><td>Full Insight (5 sections)</td></tr><tr><td>4</td><td>normal</td><td>Routine notices, digests</td><td>Key Point only</td></tr><tr><td>5</td><td></td><td>Noise - Excluded from feed</td><td></td></tr></tbody></table>

**How classification works**

Every article passes through a four-stage classification pipeline.

<figure><img src="/files/pKlku6Ym7rmsMcVDDPaI" alt=""><figcaption></figcaption></figure>

Stage 1 (L5 Noise Filter): Removes promotional noise that harms feed quality. Sponsored content, editorial-wrapped promotions, and affiliate/traffic bait are classified as Level 5 and excluded from the feed entirely. All genuine reporting, analysis, and commentary from trusted sources passes this filter regardless of topic.

**Stage 2 (L4 Filter)**: Separates routine data and analysis-thin content from news that warrants full five-section insight. Digests, routine operational notices, contextless data points, and content where analysis sections would produce only generic statements (opinions, forecasts, small-scale project updates, chart analysis, unexecuted governance proposals) are classified as Level 4.

**Stage 3 (L2 Condition Table)**: Articles that pass Stages 1 and 2 are checked against a structured condition table across seven categories. If the article's core event matches any condition, it is classified as Level 2. If no condition matches, it is classified as Level 3.

The seven categories:

1. Regulation / Legal (legislative votes, formal guidance, court rulings, enforcement actions)
2. Institutional / Product Launch (Tier-1 institution or Top-2 exchange launches)
3. Macro Data / Policy (U.S./China official data, central bank rate decisions)
4. Market Structure / Security (hacks $30M+, liquidation cascades $1B+, exchange halts, stablecoin depegs)
5. Institutional Capital Flows (public company $1B+ crypto purchase, sovereign allocation)
6. Geopolitical / Macro Shock (chokepoint disruption, war escalation with market reaction)
7. Crypto Ecosystem Shift (executive orders, mainnet upgrades, major platform crypto integration)

**Stage 4 (L1 Override)**: Only Level 2 articles are eligible for upgrade to Level 1. An article is upgraded only when all three conditions are met: systemic scope (can reprice broad risk assets market-wide), already executed (not planned or expected), and immediate transmission (impact reaches participants within hours).

**Level definitions and examples**

**Level 1 — Critical (Systemic Regime Shift)**

A systemic event requiring immediate attention from all market participants. L1 is upgraded from L2 only when all three conditions are met: systemic scope, already executed, and immediate transmission.

* FOMC emergency inter-meeting rate decision announced
* Major country enacts immediate crypto ban with enforcement
* Active military strikes close Strait of Hormuz with oil surging 30%+ in hours
* Major algorithmic stablecoin collapse (Terra/UST-level event)

Actor restrictions: macro/policy events require U.S. or China. Stablecoin events require USDT or USDC. L1 is expected to occur 0 times on most days.

**Level 2 — Important (Meaningful Market Change)**

A concrete event that changes rules, access, liquidity expectations, or institutional demand. Determined by the Stage 3 condition table across seven categories.

* Legislative vote passes on crypto-related bill
* Regulatory agency issues formal crypto guidance or framework
* Court delivers ruling in a case with industry-wide implications
* Tier-1 institution (BlackRock, Fidelity, Goldman Sachs) or Top-2 exchange launches new product or service
* U.S./China official economic data release (CPI, NFP, GDP, rate decision)
* Protocol hack with confirmed losses of $30M+
* Major energy chokepoint disrupted with market reaction described
* Executive order signed addressing crypto assets

**Level 3 — General**

Default for articles that pass Stages 1 and 2 but do not match any L2 condition. Meaningful at the project or sector level, with enough substance for five-section analysis.

* Single ecosystem operational issues, mid-size security incidents
* Token unlock/vesting/distribution changes, limited governance decisions
* Institutional pilots without market-wide access shift
* Mid-size economy macro policy
* Research reports without binding action

**Level 4 — Routine / Data**

Routine notices, digests, and content where five-section analysis would produce only generic statements.

* Summaries/digests/roundups/market updates (always Level 4)
* Routine listings/delistings, fee events, maintenance
* Contextless whale alerts, on-chain movements, standalone data points
* Analyst price predictions, chart analysis, opinion pieces without accompanying official action
* Small-scale project updates, partnership announcements below $50M
* Unexecuted governance proposals, testnet launches

Level 5 — Noise

Promotional content disguised as news. Excluded from the feed entirely.

* Sponsored articles, advertorials, paid content, exchange marketing campaigns
* Editorial-wrapped promotions for unknown projects with unverifiable claims
* Affiliate-driven ranking listicles, clickbait price predictions, recurring pick-list filler
* "How to buy" guides, presale/ICO promotions, airdrop claim guides

**I/A/T Scoring (downstream ranking)**

After classification, Level 1-3 articles are independently scored on three dimensions. They are used by Top News RSS and Daily Market Update RSS for story ranking.

* **Impact (I)**: Scope of effect (0 = narrow, 1 = sector, 2 = broad market)
* **Actionability (A)**: How concrete the core event is (0 = narrative, 1 = verifiable marker, 2 = binding/operative now)
* **Transmission (T)**: Path to crypto markets (0 = weak, 1 = plausible near-term, 2 = direct crypto infrastructure)

#### 2.2 AI Insight

Level 1–3 articles include structured analysis in five sections. Level 4 articles include Key Point only.

<table><thead><tr><th width="179.7999267578125">Section</th><th>Core question</th></tr></thead><tbody><tr><td>Key Point</td><td>What happened? Fact-only summary of the core event. Level 1–2 includes "Why it matters."</td></tr><tr><td>Market Sentiment</td><td>How is the market likely to read this event? Provides a directional label (Bullish / Cautiously Bullish / Neutral / Cautiously Bearish / Bearish) together with a catalyst label.</td></tr><tr><td>Similar Past Cases</td><td>What happened in comparable past events? Level 1–2 provides web-search-verified historical cases.</td></tr><tr><td>Ripple Effect</td><td>Where could this event spread? Transmission mechanism analysis.</td></tr><tr><td>Opportunities &#x26; Risks</td><td>What to monitor next? Conditional action cues: "If X happens, then Y is a signal to..."</td></tr></tbody></table>

#### 2.3 mentionedCoins

Related token symbols are automatically mapped to each article.

* Based on CoinMarketCap ID table (updated daily).
* Only coins that appear in the AI-generated title, summary, or Key Point are tagged. A coin mentioned only in the original article but absent from the generated output is excluded.
* Each tagged coin passes a push-alert relevance test: the coin must be the article's core subject, or individually affected by the event in a way a holder of only that coin would find relevant. Background, price-list, and analogy mentions are excluded.

#### 2.4 Translation

NS3 translation is Equivalent Comprehension Transfer.

**Purpose**: Each language reader achieves the same level of understanding and the same level of actionability as an English-reading audience.

**Core principle**: How something is said may change. What is said never changes.

* **Allowed**: Sentence splitting/merging, replacing awkward phrasing with local finance collocations, natural clause reordering
* **Forbidden**: Adding/deleting/changing facts, strengthening/weakening certainty, adding analysis/opinions/background

When translation choices conflict — for example, a locally natural phrase that slightly shifts comprehension — resolve by the following priority:

**Optimization priority**

1. Equivalent comprehension for local readers
2. Newsroom desk tone and delivery quality
3. Natural localization

Supported languages (16): English, 简体中文, 繁體中文, 한국어, 日本語, Русский, Türkçe, Deutsch, Español, Français, Tiếng Việt, ไทย, Bahasa Indonesia, हिन्दी, Italiano, Português

***

### 3. How RSS Fields Map to UI

This section shows how each RSS field is rendered in the actual NS3 app.

<figure><img src="/files/CaEztU7CmkJWsWkxwYEs" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="199.79998779296875">UI Element</th><th>RSS Field</th></tr></thead><tbody><tr><td>① Relative time</td><td><code>pubDate</code>  client converts absolute timestamp to relative format</td></tr><tr><td>② Headline title</td><td><code>title</code></td></tr><tr><td>③ AI Summary text</td><td><code>description</code></td></tr><tr><td>④ Cover image</td><td><code>media:content</code>  1–2 royalty-free cover images</td></tr><tr><td>⑤ IMPORTANT / BREAKING badge</td><td><code>newsType</code></td></tr><tr><td>⑥ Coin tags</td><td><code>mentionedCoins</code></td></tr><tr><td>⑦ AI INSIGHT button (click destination)</td><td><code>link</code></td></tr><tr><td>⑧ Full AI Insight analysis</td><td><code>insight</code>  5-section markdown (Level 1–3) / Key Point only (Level 4)</td></tr></tbody></table>

**Design principle**: All core content — headline, summary, navigation target, timestamp, image, classification, and analysis — is fully driven by RSS fields. This guarantees consistent behavior across web, mobile, and partner integrations.

Example feed: [https://ns3.ai](https://ns3.ai/)

***

### 4. Validate the Data Yourself

You can verify data quality directly before integration.

**News data & analysis quality**

Provide the RSS URL below to any AI model and ask what your platform could build with it.

```
https://api.ns3.ai/feed/news-data?lang=en
```

Example prompt:&#x20;

{% hint style="success" %}
Read the RSS feed at the following URL. Based on the data structure and content available in each item, list the specific news features and user experiences our crypto platform could build using this feed — without any additional data source or AI processing on our side.\
<https://api.ns3.ai/feed/news-data?lang=en>
{% endhint %}

**Translation quality**

Provide two RSS URLs — one in English and one in your target language — to any AI model and ask whether users in both languages would receive the same information.

```
https://api.ns3.ai/feed/news-data?lang=[code]
```

Replace the language code to test any of the 16 supported languages: \
`en · zh-CN · zh-TW · ko · ja · ru · tr · de · es · fr · vi · th · id · hi · it · pt`

Example prompt:&#x20;

{% hint style="success" %}
Read the news data at the following URLs — one in English and one in Korean. Compare the two and evaluate whether a Korean-speaking user would get the same level of information and the same ability to act on the news as an English-speaking user.\
<https://api.ns3.ai/feed/news-data?lang=en\\>
<https://api.ns3.ai/feed/news-data?lang=ko>
{% endhint %}

***

<details>

<summary>Technical specification for developers starts below</summary>

Section 5-12 is documentation for developers.

</details>

### 5. RSS URL & Languages

#### Base URL

```
https://api.ns3.ai/feed/news-data?lang=en
```

#### 16 Language URLs

<table><thead><tr><th width="149.79998779296875">Language</th><th width="99.79998779296875">Code</th><th>URL</th></tr></thead><tbody><tr><td>English</td><td>en</td><td><code>https://api.ns3.ai/feed/news-data?lang=en</code></td></tr><tr><td>简体中文</td><td>zh-CN</td><td><code>https://api.ns3.ai/feed/news-data?lang=zh-CN</code></td></tr><tr><td>繁體中文</td><td>zh-TW</td><td><code>https://api.ns3.ai/feed/news-data?lang=zh-TW</code></td></tr><tr><td>한국어</td><td>ko</td><td><code>https://api.ns3.ai/feed/news-data?lang=ko</code></td></tr><tr><td>日本語</td><td>ja</td><td><code>https://api.ns3.ai/feed/news-data?lang=ja</code></td></tr><tr><td>Русский</td><td>ru</td><td><code>https://api.ns3.ai/feed/news-data?lang=ru</code></td></tr><tr><td>Türkçe</td><td>tr</td><td><code>https://api.ns3.ai/feed/news-data?lang=tr</code></td></tr><tr><td>Deutsch</td><td>de</td><td><code>https://api.ns3.ai/feed/news-data?lang=de</code></td></tr><tr><td>Español</td><td>es</td><td><code>https://api.ns3.ai/feed/news-data?lang=es</code></td></tr><tr><td>Français</td><td>fr</td><td><code>https://api.ns3.ai/feed/news-data?lang=fr</code></td></tr><tr><td>Tiếng Việt</td><td>vi</td><td><code>https://api.ns3.ai/feed/news-data?lang=vi</code></td></tr><tr><td>ไทย</td><td>th</td><td><code>https://api.ns3.ai/feed/news-data?lang=th</code></td></tr><tr><td>Bahasa Indonesia</td><td>id</td><td><code>https://api.ns3.ai/feed/news-data?lang=id</code></td></tr><tr><td>हिन्दी</td><td>hi</td><td><code>https://api.ns3.ai/feed/news-data?lang=hi</code></td></tr><tr><td>Italiano</td><td>it</td><td><code>https://api.ns3.ai/feed/news-data?lang=it</code></td></tr><tr><td>Português</td><td>pt</td><td><code>https://api.ns3.ai/feed/news-data?lang=pt</code></td></tr></tbody></table>

`lang` is a required parameter. All other parameters are optional.

***

### 6. Item Field Specification

#### 6.1 Standard RSS Fields

```xml
<item>
  <title><![CDATA[Bitcoin falls to $68,000 as Middle East conflict revives crypto volatility]]></title>
  <description><![CDATA[Bitcoin fell back to about $68,005, down around 3% over the past day after briefly trading above $70,000 this week. Spot Bitcoin exchange-traded funds saw about $576.8 million in redemptions on Thursday and Friday after earlier inflows.]]></description>
  <link>https://ns3.ai/en/news/wTdCkiJv36</link>
  <guid isPermaLink="true">https://ns3.ai/en/news/wTdCkiJv36</guid>
  <pubDate>Sat, 07 Mar 2026 15:04:45 GMT</pubDate>
  <insight><![CDATA[## Key Point
Bitcoin fell back to about $68,005, down around 3% over the past day.
## Market Sentiment
Cautiously Bearish, Macro-driven
Reason: The combination of geopolitical tension and ETF outflows pressures risk assets.
## Similar Past Cases
Analysis of comparable past events and outcomes.
## Ripple Effect
Transmission mechanism analysis.
## Opportunities & Risks
**Opportunities**: Conditional opportunity cues.
**Risks**: Conditional risk cues.]]></insight>
  <mentionedCoins>BTC,ETH,XRP</mentionedCoins>
  <storyKey>{"entity":["btc"],"action":"report","figure":["68k"],"keywords":["btc","middle-east","iran"]}</storyKey>
  <newsType>normal</newsType>
  <level>3</level>
  <media:content medium="image" url="https://assemble-ai-files.s3.amazonaws.com/<image-1>"> </media:content>
  <media:content medium="image" url="https://assemble-ai-files.s3.amazonaws.com/<image-2>"> </media:content>
</item>
```

**`title`**

* Meaning: AI-generated news headline
* Type: `string` (CDATA-wrapped)
* Use: Primary headline text in feed lists

**`description`**

* Meaning: Core summary of the original article (1–4 sentences)
* Type: `string` (CDATA-wrapped)
* Use: Article preview snippet
* Note: CDATA-wrapped; the content is plain text, not HTML. Normalize whitespace and line breaks on the client side.

**`link`**

* Meaning: NS3 AI INSIGHT page URL (click destination)
* Type: `URL string`
* Use: Used when linking to the NS3 Insight page rather than serving AI Insight internally.

**`guid`**

* Meaning: Unique item identifier (deduplication, update tracking)
* Type: `URL string`, `isPermaLink="true"`
* Note: Currently matches `link`, but do not assume they always match.
* Recommended: Use `guid` for deduplication, `link` for navigation.

**`pubDate`**

* Meaning: Publish time from the original source
* Type: RFC 822/1123 format (e.g., `Tue, 27 Jan 2026 06:33:37 GMT`)
* Use: Timeline ordering, "3 min ago / 2 hours ago" display

**`media:content`**

* Meaning: Cover images for the article — royalty-free and free for partners to use.
* Type: URL string, `medium="image"`. Delivered as **1–2 repeated `<media:content>` elements** per item.
* Selection: Cover images are matched from the NS3 image library based on the article's key subjects. Each subject is backed by a group of images, and one is selected at random — so the same subject may appear with different images across articles.
* Default: When no match is found, a single `<media:content>` returns the NS3 default logo (`https://ns3.ai/default.png`). The image field is never empty.
* Default replacement: If a cover image URL is `https://ns3.ai/default.png`, partners may replace it with their own image.
* Size & ratio: Cover images are either **square or landscape (wide) rectangles**, and vary in size — they are not standardized, since partners' preferred ratios differ.
* Usage: Use one image, or compose multiple freely (e.g., two images side by side). Depending on your UI, a **1.91:1 (landscape) or 1:1 (square) display frame is recommended** — 1.91:1 for desktop and link-preview surfaces, 1:1 for mobile and compact surfaces. Render with `object-fit: cover` for uniform cards, and avoid heavy upscaling of small images.

**Cover image composition (NS3 reference pattern)**

The feed delivers **1–2 cover images per article — never zero** (when no library image matches, the NS3 default logo fills the slot). Cover images vary in size and aspect ratio and are not standardized; partners may compose them however they prefer. For reference, NS3's own apps render them as follows:

* **Desktop — 1.91:1 landscape frame:** when one image is provided, it fills the frame; when two images are provided, they are shown as a side-by-side split cover (X / Twitter style). On desktop, all provided images are used.
* **Mobile — 1:1 square frame:** only one image is used — the primary image (`media:content[0]`) — even when two images are provided.

The first `<media:content>` element is the article's primary subject; use it as the representative image for single-image and mobile layouts. Partners are encouraged to reference this pattern and adapt it to their own UI. A 1.91:1 frame suits desktop and link-preview surfaces; 1:1 suits mobile and compact surfaces.

**Recommended composition by frame ratio:**

* **1:1 (square) frame:** use a single cover image. The first image (`media:content[0]`) is the most relevant, so use it.
* **1.91:1 (landscape) frame:** use one or both images. When two images are provided, a side-by-side split cover (X / Twitter style) is recommended; a single image also displays well in a 1.91:1 frame.

In short, partners can implement a variety of cover styles depending on their UI.

<figure><img src="/files/Aa3R6SMNc7K9ziO9RXCz" alt=""><figcaption><p><strong>A single cover image.</strong> When the feed returns one image, it fills the full 1.91:1 frame.</p></figcaption></figure>

<figure><img src="/files/0dYDAjl02qobTj0VbNck" alt=""><figcaption><p><strong>Two cover images, composed side by side.</strong> When the feed returns two <code>&#x3C;media:content></code> images, they can be rendered as a split cover — X (Twitter) style.</p></figcaption></figure>

Tip: The two-image split mirrors how X (Twitter) lays out a two-image post. It works well for stories involving two entities.

#### 6.2 NS3 Extended Fields

**`mentionedCoins`**

* Meaning: Token symbols related to the article
* Type: `string` (CSV format, e.g., `BTC,ETH,SOL`)
* Note: **May be missing.** If no token is explicitly mentioned, the value may be empty or the tag absent.
* Parsing: Split by `,` → trim each item → normalize to uppercase

**`newsType`**

* Meaning: AI-assigned news type
* Values: `normal` | `important` | `breaking`
* Type: `enum string`
* Use: "Breaking only", "Important only" UI filters

**`level`**

* Meaning: AI-assigned news importance (1 = most important)
* Values: `1` | `2` | `3` | `4` | `5`
* Type: `integer`
* Use: Push notification / exposure priority policy
* Note: Level 5 is excluded from the RSS feed.

**`storyKey`**

* Meaning: Structured event identifier used for clustering and cross-article discovery.
* Type: JSON object serialized as a string inside the `<storyKey>` element, or null for Level 5 articles (which are excluded from the feed anyway).
* Clustering role: `entity`, `action`, and `figure` together form the clustering key. Articles that share the same actor, action, and key figure describe the same event. `keywords` is a separate discovery tag array and is not used for clustering.

<table><thead><tr><th width="120.111083984375">Field</th><th width="259.6666259765625">Meaning</th><th>Example values</th></tr></thead><tbody><tr><td>entity</td><td>Primary actor or subject (array of 1–2)</td><td><code>["sec"]</code>, <code>["blackrock"]</code>, <code>["trump","iran"]</code></td></tr><tr><td>action</td><td>Core action category from a fixed list</td><td><code>ruling</code>, <code>launch</code>, <code>hack</code>, <code>agreement</code></td></tr><tr><td>figure</td><td>Key numeric value, or none (array of 1–2)</td><td><code>["329.9m"]</code>, <code>["15pct"]</code>, <code>["none"]</code></td></tr><tr><td>keywords</td><td>Discovery tag array (3–8 items)</td><td><code>["strategy","btc","treasury","saylor"]</code></td></tr></tbody></table>

**Using the `keywords` field:**

* **Prediction market contract mapping** — match news to prediction market contracts (e.g., Polymarket, Kalshi) by comparing contract topic tags with article `keywords`.
* **Related news grouping** — power "related news" rails and cross-article discovery based on shared topic tags, even across different story clusters.
* **Cover image mapping** — the article's keywords are matched against the image library to select the cover image(s) delivered in `media:content`. Keywords are ordered by importance, so the leading keywords drive the primary cover image (and, when two images are returned, the second). When no keyword matches the library, the NS3 default logo (`https://ns3.ai/default.png`) is returned.
* **Topic watchlists and alerts** — let users subscribe to topics rather than only coins (e.g., `fomc`, `ceasefire`, `hormuz`, `tariff`) and push alerts when matching articles appear. Particularly useful for users focused on macro and geopolitical risk.
* **Theme filters beyond tickers** — filter by themes that `mentionedCoins` cannot capture, such as `tokenization`, `regulation`, `rwa`, or `ipo`, for themed dashboards and research surfaces.

#### 6.3 AI Insight Field

**`insight`**

* Meaning: Full AI structured analysis
* Type: string (CDATA-wrapped, markdown format). Render as rich text or parse individual sections by splitting on `##` headings.
* Section delimiter: `##` headings

**Level 1–3 structure:**

```xml
<insight><![CDATA[## Key Point
Fact-based core summary from the article.

Why it matters: (Level 1–2 only)

## Market Sentiment
Cautiously Bullish, Regulatory-driven

Reason: Rationale for the directional label.

## Similar Past Cases
Analysis of comparable past events and outcomes.

## Ripple Effect
Transmission mechanism analysis.

## Opportunities & Risks
**Opportunities**: Conditional opportunity cues.

**Risks**: Conditional risk cues.]]></insight>
```

**Level 4 structure:**

```xml
<insight><![CDATA[## Key Point
Core event summary. (2–3 sentences)]]></insight>
```

**Parsing guide**: Split on the `##` string to extract individual sections. Depending on your platform's needs, render the full insight or selectively use specific sections.

***

### 7. Filtering (URL Parameters)

All filter parameters are appended to the base URL as `&key=value`. URL-encode parameter values when they contain reserved characters.

#### 7.1 Token filter: `crypto` (multi)

Returns only news related to a specific token.

```
https://api.ns3.ai/feed/news-data?lang=en&crypto=BTC
https://api.ns3.ai/feed/news-data?lang=en&crypto=BTC,ETH
```

#### 7.2 News type filter: `newsType` (single)

```
https://api.ns3.ai/feed/news-data?lang=en&newsType=important
```

#### 7.3 Exclude sources: `excludeSources` (multi)

Source IDs are listed in the table in Section 8.

```
https://api.ns3.ai/feed/news-data?lang=en&excludeSources=2
https://api.ns3.ai/feed/news-data?lang=en&excludeSources=1,2
```

If `,` is a reserved character in your environment, use URL encoding: `excludeSources=1%2C2`

#### 7.4 Exclude levels: `excludeLevels` (multi)

Excludes articles at specific levels.

<table><thead><tr><th width="69.79998779296875">Level</th><th width="110.39996337890625">newsType</th><th width="314.599853515625">Meaning</th><th>Insight</th></tr></thead><tbody><tr><td>1</td><td>breaking</td><td>Event that can move the entire market immediately</td><td>Full Insight (5 sections)</td></tr><tr><td>2</td><td>important</td><td>Event that can realistically change market rules, access, or liquidity expectations</td><td>Full Insight (5 sections)</td></tr><tr><td>3</td><td>normal</td><td>General crypto news</td><td>Full Insight (5 sections)</td></tr><tr><td>4</td><td>normal</td><td>Routine notices, digests</td><td>Key Point only</td></tr><tr><td>5</td><td></td><td>Noise - Excluded from feed</td><td></td></tr></tbody></table>

```
https://api.ns3.ai/feed/news-data?lang=en&excludeLevels=4
https://api.ns3.ai/feed/news-data?lang=en&excludeLevels=1,2,3
```

#### **7.5 Exclude categories: `excludeCategories` (multi)**

Excludes articles in specific categories. Category IDs:

<table><thead><tr><th width="100.22222900390625">ID</th><th>Category</th></tr></thead><tbody><tr><td>1</td><td>Market Trends</td></tr><tr><td>2</td><td>Regulation &#x26; Policy</td></tr><tr><td>3</td><td>Institutional Updates</td></tr><tr><td>4</td><td>Market Outlook &#x26; Expert Views</td></tr><tr><td>5</td><td>General</td></tr><tr><td>6</td><td>Exchange &#x26; Venue Operations</td></tr><tr><td>7</td><td>Macro &#x26; Geopolitical</td></tr><tr><td>8</td><td>Security &#x26; Incidents</td></tr></tbody></table>

Example: Exclude exchange listing news and routine notices:

```
https://api.ns3.ai/feed/news-data?lang=en&excludeCategories=6
```

Multiple categories can be excluded:

```
https://api.ns3.ai/feed/news-data?lang=en&excludeCategories=6,7
```

#### **7.6 Result limit: `limit` (single)**

Controls the number of items returned. Default is 100.

```
https://api.ns3.ai/feed/news-data?lang=en&limit=20
```

<table><thead><tr><th width="143.22222900390625">limit</th><th width="202.4444580078125">Estimated tokens</th><th>Use case</th></tr></thead><tbody><tr><td>10</td><td>~7,000–9,500</td><td>Quick scan</td></tr><tr><td>20</td><td>~14,000–19,000</td><td>Recommended default</td></tr><tr><td>50</td><td>~35,000–47,500</td><td>Broad range</td></tr><tr><td>100 (default)</td><td>~68,000–94,000</td><td>Full feed</td></tr></tbody></table>

Token estimates are based on Level 2–3 articles (5-section insight included). Level 4 articles contain Key Point only and are significantly lighter at approximately 250 tokens per item.

This parameter was introduced primarily for AI agent integrations, where each RSS fetch consumes context window tokens. Reducing the item count directly reduces token cost per call. For traditional polling integrations, `limit` is also useful when the platform only needs a fixed number of recent items per poll cycle (e.g., displaying the latest 10 articles on a homepage widget), reducing payload size and parse time.

`limit` controls only the number of items returned. Increasing the limit does not produce new news. It adds older articles. Combine with filters for best results:

```
https://api.ns3.ai/feed/news-data?lang=en&crypto=BTC&limit=20
```

#### **7.7 Recommended filter for exchanges**

When using News RSS as the news feed on an exchange platform, competitor exchange listings, fee changes, and routine operational notices are typically unwanted. The following filter combination blocks approximately 99% of other exchange-related news:

```
https://api.ns3.ai/feed/news-data?lang=en&excludeCategories=6&excludeLevels=4
```

<table><thead><tr><th width="207.77777099609375">Parameter</th><th>Effect</th></tr></thead><tbody><tr><td><code>excludeCategories=6</code></td><td>Removes Exchange &#x26; Venue Operations (competitor listings, fee changes, regional expansion, maintenance, system updates, exchange-targeted regulatory actions)</td></tr><tr><td><code>excludeLevels=4</code></td><td>Removes routine notices and data-only articles.</td></tr></tbody></table>

#### 7.8 Combined filters

Multiple parameters can be combined.

BTC-related news only, exchange operations excluded, promotional noise excluded, latest 20 items:&#x20;

```
https://api.ns3.ai/feed/news-data?lang=en&crypto=BTC&excludeCategories=6&excludeLevels=4&limit=20
```

***

### 8. Original Source Media

Media sources by NS3. Use the source ID with the `excludeSources` parameter.

<table><thead><tr><th width="99.79998779296875">ID</th><th>Source Name</th></tr></thead><tbody><tr><td>1</td><td>Cointelegraph</td></tr><tr><td>2</td><td>CoinDesk</td></tr><tr><td>3</td><td>CoinMarketCap</td></tr><tr><td>4</td><td>Watcher.Guru</td></tr><tr><td>5</td><td>The Daily Hodl</td></tr><tr><td>6</td><td>Beincrypto</td></tr><tr><td>7</td><td>Decrypt</td></tr><tr><td>8</td><td>The Block</td></tr><tr><td>9</td><td>Bloomberg Crypto</td></tr><tr><td>10</td><td>Forbes Crypto</td></tr><tr><td>11</td><td>Reuters Crypto</td></tr><tr><td>12</td><td>Fortune Crypto</td></tr><tr><td>13</td><td>CoinNess</td></tr><tr><td>14</td><td>Odaily</td></tr><tr><td>15</td><td>CryptoSlate</td></tr><tr><td>16</td><td>Bitcoin Magazine</td></tr><tr><td>17</td><td>DL News</td></tr><tr><td>18</td><td>The Defiant</td></tr><tr><td>19</td><td>Protos</td></tr><tr><td>20</td><td>Wu Blockchain</td></tr></tbody></table>

***

### 9. Error Handling & Edge Cases

Client implementations should handle the following cases by default.

#### 9.1 Default cover image

* Cause: No matching image was found in the NS3 image library for the article's key subjects.
* Behavior: A single `<media:content>` returns the NS3 default logo (`https://ns3.ai/default.png`). The image field is never empty.
* Product: Display the default as-is, or detect the `https://ns3.ai/default.png` URL and substitute your own brand image.
* Engineering: Expect 1–2 `<media:content>` elements per item. Iterate all of them rather than reading only the first.

#### 9.2 Missing or empty `mentionedCoins`

* Cause: No token is explicitly mentioned, or AI cannot confidently map symbols.
* Product: Hide the coin tag area.
* Engineering: Allow both missing tag and empty string. If parsing yields an empty array, treat as "no tokens."

#### 9.3 Potential `guid` vs `link` mismatch

* guid and link currently share the same value, but this is not guaranteed. They may diverge in future updates.
* Use `guid` for deduplication, `link` for navigation.

#### 9.4 `pubDate` parsing failure

* `pubDate` is typically RFC 822/1123, but environments may vary.
* Engineering: Parse RFC 822/1123 first, then fall back to ISO 8601 (defensive parsing).

#### 9.5 `insight` field handling

* Level 1–3: Contains all 5 sections.
* Level 4: Contains `## Key Point` section only.
* When splitting on `##` , account for the variable number of sections.

#### 9.6 **HTTP error handling**

<table><thead><tr><th width="150.33331298828125">Status</th><th>Meaning</th><th>Recommended action</th></tr></thead><tbody><tr><td>200</td><td>Success</td><td>Process feed normally</td></tr><tr><td>304</td><td>Not Modified</td><td>Use cached version (when conditional request headers are supported)</td></tr><tr><td>400</td><td>Bad Request (e.g., invalid <code>lang</code> code)</td><td>Check parameter values</td></tr><tr><td>500, 502, 503</td><td>Server error</td><td>Retry after 30–60 seconds. Do not retry immediately in a tight loop.</td></tr></tbody></table>

> If the server is unreachable or returns a non-200 response, continue serving the last successfully fetched feed until the next successful poll.

***

### 10. Polling & Caching

News RSS updates in real time.

#### Recommended polling interval

* 5 minute – 15 minutes
* Adjust based on traffic, cost, and UX balance.

#### Caching principles

* If the server provides `ETag` / `Last-Modified`, use conditional requests (`If-None-Match` / `If-Modified-Since`).
* If not provided: Set a short client-side TTL (e.g., 1–5 minutes) and refresh.
* Feeds are limited to the latest 100 items. Clients inactive for extended periods may miss intermediate items.

***

### 11. Implementation Checklist

* [x] Deduplicate using `guid` (navigate using `link`)
* [x] Handle missing `media:content` with thumbnail fallback
* [x] Parse `mentionedCoins` CSV into a list (allow empty)
* [x] Treat `newsType` as a 3-value enum
* [x] Implement push/priority logic based on `level`
* [x] Parse `insight` markdown (split sections on `##` )
* [x] Account for Level 4 insight containing Key Point only
* [x] Support 16 languages via `lang` parameter
* [x] Set polling interval (5–15 minutes recommended)
* [x] Defensive `pubDate` parsing (RFC 822 + ISO 8601 fallback)

***

### 12. FAQ

**Q: How many Level 1 articles occur per day?**

Level 1 is reserved for system-level events that can move the entire market immediately. Most days produce zero. Even during major events, expect 1–2 per day at most. Level 2 articles average 30–50 per weekday. The majority of articles are Level 3.

**Q: Is newsType "breaking" the same as a News Flash RSS headline?**

No. newsType "breaking" is a classification assigned by the news analysis AI based on an individual article's importance. News Flash RSS is a separate feed produced by a different pipeline (paid breaking news services → AI rewrite). The sources and production processes are entirely different.

**Q: How many articles are included in a feed?**

Each RSS URL returns the latest 100 items by default. Use the `limit` parameter to reduce the number of items returned (e.g., `limit=20` returns the latest 20). Filters such as `crypto`, `newsType`, and `excludeCategories` narrow the scope first, then the feed returns up to 100 (or the specified limit) items within that scope. Increasing the limit does not produce new news. It adds older articles.

**Q: If a digest article contains a major event, does its Level get elevated?**

No. Digest/roundup/market update articles are always Level 4, regardless of what they contain.

**Q: Why do multiple articles about the same event appear?**

NS3 reads articles from 20+ media outlets. When multiple outlets cover the same event, each is analyzed and delivered independently. Every article includes a `storyKey` field (entity, action, figure, keywords) that identifies which event it belongs to. Articles that share the same entity, action, and figure describe the same story. Partners can use storyKey to build their own story grouping or deduplication. For pre-built story clustering, use Top News RSS, which groups related articles and delivers a ranked Top 10.

**Q: Can I receive only articles at specific levels?**

Use the `excludeLevels` parameter to exclude specific levels. For example, `&excludeLevels=4` delivers only Level 1–3 articles. `newsType=important` filters to Level 2 articles only.

**Q: Where do the cover images come from, and can they be missing?**

Each article includes **1–2 NS3 cover images**, delivered as `<media:content>` elements. These are royalty-free, NS3-supplied images selected from an image library based on the article's keyword. The image field is **never empty**: when no library image matches, the NS3 default logo (`https://ns3.ai/default.png`) is returned, which you may replace with your own image. Note that the same subject may appear with different images across articles, since each subject is backed by a group of images selected at random. For display, a 1.91:1 (landscape) or 1:1 (square) frame is recommended depending on your UI.

**Q: Why are some on-chain movement or liquidation articles classified as Level 4?**

When an article reports only a data point (e.g., a wallet transfer with no stated reason, a small liquidation snapshot, or a price-level crossing with no catalyst), there is nothing to analyze beyond the headline. These articles receive Key Point only. If the same type of article includes a stated cause, a known-event connection, or systemic framing, it passes to Level 3 with full analysis.

**Q: Are geopolitical or macro news articles excluded as off-domain?**

No. All genuine reporting from trusted sources passes the feed regardless of topic. Geopolitical events, macroeconomic data, and traditional finance news are classified at Level 2-4 based on their market impact. Only promotional noise (sponsored content, affiliate listicles, editorial-wrapped promotions) is excluded as Level 5.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ns3.ai/ns3-api/news-rss.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.