# News RSS

<figure><img src="https://4099730103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fypf00vlh3dJz4PJ2Q67s%2Fuploads%2Fn9qaRalCQkqWAkCIzqOC%2FDOC7.png?alt=media&#x26;token=858a617d-17ab-45e7-88da-40340b39ace2" 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 RSS 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="https://4099730103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fypf00vlh3dJz4PJ2Q67s%2Fuploads%2FLxHJdvNmZ0XEl9KDUnQX%2Fnews%20do.png?alt=media&#x26;token=c67a7b24-3e48-49f2-9361-aa6d4f0e3c27" 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 directional label (Bullish/Bearish/Neutral) + 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 explicitly mentioned in the article are included
* Sorted by relevance: core asset → directly impacted asset → structural role asset

#### 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="https://4099730103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fypf00vlh3dJz4PJ2Q67s%2Fuploads%2FffuD0D43qBRZlLZaEfbc%2FNews%20rss-01.png?alt=media&#x26;token=d2959d72-a61c-42a2-abab-8787541fba12" 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>④ Thumbnail image</td><td><code>media:content</code> — falls back to default image when missing</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>
    <media:content medium="image" url="https://example.com/image.jpg">
    </media:content>
    <mentionedCoins>BTC,ETH,XRP</mentionedCoins>
    <newsType>normal</newsType>
    <level>3</level>
    <storyKey>
  <entity>bitcoin</entity>
  <action>decline</action>
  <target>middle-east-conflict</target>
  <figure>68000</figure>
</storyKey>
    <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>
</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: Social preview image URL from the original source
* Type: `URL string`, `medium="image"`
* Note: **May be missing.** Some sources do not provide preview images.

#### 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 for story clustering. Encodes the core event as four fields: who did what to whom, with what figure.
* Type: `object` with four string fields, or `null`
* Clustering logic: Two articles describe the same story when 3 or more of the 4 fields match.

<table><thead><tr><th width="115.66668701171875">Field</th><th width="258.22222900390625">Meaning</th><th>Example values</th></tr></thead><tbody><tr><td>entity</td><td>Primary actor or subject</td><td><code>sec</code>, <code>blackrock</code>, <code>trump</code>, <code>bitcoin</code></td></tr><tr><td>action</td><td>Core action or event type</td><td><code>ruling</code>, <code>launch</code>, <code>agreement</code>, <code>suspension</code></td></tr><tr><td>target</td><td>Object, instrument, or context</td><td><code>ripple-lawsuit</code>, <code>spot-btc-etf</code>, <code>iran-war</code></td></tr><tr><td>figure</td><td>Key numeric value, or <code>none</code></td><td><code>500m</code>, <code>30pct</code>, <code>none</code></td></tr></tbody></table>

#### 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></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 Missing `media:content` (no image)

* Cause: The original source does not provide a social preview image.
* Product: Use a default image/logo or a no-image card layout.
* Engineering: Treat missing `media:content@url` as null. Do not throw exceptions.

#### 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, target, figure) that identifies which event it belongs to. Articles with 3 or more matching storyKey fields 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: Why are some articles missing images?**

The original source does not provide a social preview image. Handle this in your UI with a default image or a no-image layout.

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