---
name: Tickr
description: Use when building trading bots, quant algorithms, or financial news aggregation tools. Reach for this skill when you need to fetch breaking financial news, stream real-time market updates, search historical articles, or integrate ticker-specific sentiment analysis into trading systems.
metadata:
    mintlify-proj: tickr
    version: "1.0"
---

# TradingNews API (tickr) Skill

## Product Summary

TradingNews is a unified trading news API that aggregates breaking financial news from multiple sources into a single, structured stream. Agents use it to fetch recent articles via REST, stream real-time updates via WebSocket, search historical articles semantically (Max plan), and retrieve per-ticker sentiment analysis. The API is rate-limit-based (Starter: 1 req/min, Pro: 30 req/min, Max: 60 req/min) with no per-request credits or overage charges.

**Base URL:** `https://api.tradingnews.press`  
**Authentication:** `X-API-Key` header (format: `tn_live_*` for production)  
**Key files/concepts:** API keys, rate limits, article schema (id, content, urgency, sentiment, published_at, received_at, tickers)  
**Primary docs:** https://docs.tradingnews.press

## When to Use

Reach for this skill when:
- **Fetching recent news** — Agent needs to query articles from the last 24h (Starter) or 7 days (Pro/Max) via REST
- **Real-time streaming** — Agent needs live article firehose for a trading bot or alert system (Pro/Max plans only)
- **Semantic search** — Agent needs to find articles matching a natural-language query like "Fed interest rate decision" (Max plan only)
- **Ticker sentiment** — Agent needs per-ticker sentiment labels on articles (Max plan only)
- **Monitoring urgency levels** — Agent needs to filter for breaking/flash/regular articles
- **Checking plan limits** — Agent needs to verify current tier and rate limit before making requests

Do not use this skill for: account management, billing changes, or dashboard operations (those are web-only).

## Quick Reference

### API Endpoints

| Method | Path | Purpose | Access | Rate Limit |
|--------|------|---------|--------|-----------|
| GET | `/v1/news` | Fetch recent articles | All tiers | Counts |
| GET | `/v1/news/search` | Semantic search archive | Max only | Counts |
| WS | `/v1/stream` | Real-time firehose | Pro, Max | Unlimited |
| GET | `/v1/account/usage` | Check plan/rate limit | All tiers | Free |

### Article Schema

| Field | Type | Always Present | Notes |
|-------|------|---|---|
| `id` | string | Yes | ULID, sortable by time |
| `content` | string | Yes | Headline or full text |
| `urgency` | string | Yes | `breaking`, `flash`, or `regular` |
| `sentiment` | string? | Yes | Sentiment label (null if unavailable) |
| `published_at` | string? | Yes | ISO 8601 publication time |
| `received_at` | string | Yes | ISO 8601 when TradingNews received it |
| `tickers` | object[] | Max only | `[{"ticker": "AAPL", "sentiment": "positive"}]` |

### Rate Limits & Plans

| Plan | Price | Req/Min | WebSocket | Search | Per-Ticker Sentiment |
|------|-------|---------|-----------|--------|----------------------|
| Starter | $20/mo | 1 | No | No | No |
| Pro | $50/mo | 30 | Yes | No | No |
| Max | $100/mo | 60 | Yes | Yes | Yes |

**Data retention:** Starter can query last 24h; Pro/Max can query last 7 days. Older `since` values are silently clamped.

### Common cURL Patterns

```bash
# Fetch 5 breaking articles
curl -H "X-API-Key: tn_live_YOUR_KEY" \
  "https://api.tradingnews.press/v1/news?limit=5&urgency=breaking"

# Fetch articles since a specific time
curl -H "X-API-Key: tn_live_YOUR_KEY" \
  "https://api.tradingnews.press/v1/news?since=2026-04-07T00:00:00Z"

# Search (Max plan only)
curl -H "X-API-Key: tn_live_YOUR_KEY" \
  "https://api.tradingnews.press/v1/news/search?q=Fed%20interest%20rate"

# Check usage
curl -H "X-API-Key: tn_live_YOUR_KEY" \
  "https://api.tradingnews.press/v1/account/usage"
```

## Decision Guidance

### When to Use REST vs WebSocket

| Scenario | Use REST `/v1/news` | Use WebSocket `/v1/stream` |
|----------|---|---|
| Polling for updates every few seconds | No — hits rate limit fast | Yes — unlimited, real-time |
| One-time fetch of recent articles | Yes | No |
| Building a trading alert system | No — too slow | Yes (Pro/Max only) |
| Backfilling historical data | Yes | No |
| Starter plan | Yes (only option) | Not available |

### When to Use Semantic Search vs Filtering

| Need | Use `/v1/news` + filter | Use `/v1/news/search` |
|------|---|---|
| Get all breaking articles | Yes (`?urgency=breaking`) | No |
| Find articles about "Fed policy" | No — not available | Yes (Max only) |
| Filter by time range | Yes (`?since=...`) | No |
| Rank by relevance to a query | No | Yes (Max only) |

### Starter vs Pro vs Max

| Decision | Choose Starter | Choose Pro | Choose Max |
|----------|---|---|---|
| Budget-conscious, low volume | Yes | No | No |
| Need real-time streaming | No | Yes | No |
| Need semantic search | No | No | Yes |
| Need per-ticker sentiment | No | No | Yes |
| High-frequency polling (30+ req/min) | No | Yes | Yes |

## Workflow

### Typical Task: Fetch and Process Breaking News

1. **Verify API key and plan**
   - Call `GET /v1/account/usage` to confirm tier and rate limit
   - Check if plan supports required features (WebSocket, search, sentiment)

2. **Fetch articles**
   - For REST: `GET /v1/news?limit=50&urgency=breaking`
   - For WebSocket: Connect to `wss://api.tradingnews.press/v1/stream?api_key=YOUR_KEY` (Pro/Max only)
   - Inspect response for `count` and `articles` array

3. **Parse article fields**
   - Extract `id`, `content`, `urgency`, `sentiment`, `published_at`, `received_at`
   - If Max plan: also extract `tickers` array for per-ticker sentiment

4. **Handle errors**
   - `401` — Invalid/missing API key
   - `403` — Key inactive or plan doesn't support endpoint
   - `429` — Rate limit exceeded; wait and retry
   - `503` — Embedding service down (search only); retry shortly

5. **Implement caching/backoff**
   - Cache REST responses for 5–10 seconds to avoid rate limit
   - For WebSocket: implement exponential backoff reconnection (start 1s, cap at 60s)
   - Monitor `period_end` to detect subscription expiry

### Typical Task: Search Historical Articles (Max Plan)

1. **Construct natural-language query** (2–500 characters)
   - Example: "Fed interest rate decision", "Apple earnings beat"

2. **Call `/v1/news/search?q=YOUR_QUERY&limit=20`**
   - Returns articles ranked by semantic relevance
   - Each article includes `tickers` array with per-ticker sentiment

3. **Handle Max-plan-only errors**
   - `403` — Requesting key is not Max plan
   - `503` — Embedding service temporarily unavailable

## Common Gotchas

- **API key exposed in client-side code** — Always call TradingNews from your backend server. Never embed keys in JavaScript, React, or public repos.

- **WebSocket connection limit** — Each user is limited to 1 concurrent connection. Attempting a second connection returns close code `1008`. Close the old connection before opening a new one.

- **Starter plan data retention** — Starter keys can only query the last 24 hours. Pro/Max can reach back 7 days. Older `since` values are silently clamped; no error is raised.

- **Rate limit sliding window** — Limits are per-minute, not per-second. Bursting all requests in the first second of a minute will hit the limit. Spread requests evenly.

- **IP-based abuse protection** — Using 3+ different API keys from the same IP within 1 minute triggers a 10-minute IP block. Don't credential-stuff.

- **WebSocket plan requirement** — Starter plan connections are rejected with close code `1008`. Only Pro and Max support streaming.

- **Semantic search is Max-only** — Calling `/v1/news/search` with a Starter or Pro key returns `403`. No fallback to REST filtering.

- **Per-ticker sentiment is Max-only** — The `tickers` field is absent from Starter/Pro responses. Don't assume it exists; check plan first.

- **Subscription expiry mid-stream** — WebSocket connections are re-checked every 5 minutes. If your subscription expires, the server closes the connection with code `1008`. Implement reconnection logic.

- **Sentiment field can be null** — Not all articles have sentiment labels. Check for `null` before using.

- **Published_at can be null** — Some articles may not have a publication time. Use `received_at` as a fallback.

## Verification Checklist

Before submitting work with TradingNews:

- [ ] API key is stored in environment variables, not hardcoded
- [ ] Verified plan tier supports required features (WebSocket, search, sentiment) via `/v1/account/usage`
- [ ] Tested error handling for `401`, `403`, `429`, `503` responses
- [ ] For REST: implemented caching or request spreading to avoid rate limit
- [ ] For WebSocket: implemented exponential backoff reconnection logic
- [ ] Checked that `sentiment` and `published_at` fields can be `null` before using
- [ ] For Max plan: confirmed `tickers` array is present in responses
- [ ] For Starter plan: confirmed queries don't exceed 24-hour window
- [ ] Tested with actual API key (not placeholder)
- [ ] Verified response schema matches article structure (id, content, urgency, etc.)

## Resources

**Comprehensive page-by-page navigation:** https://docs.tradingnews.press/llms.txt

**Critical documentation pages:**
- [API Overview](https://docs.tradingnews.press/api-reference/overview) — Base URL, authentication, response format, article schema
- [Get News](https://docs.tradingnews.press/api-reference/get-news) — REST endpoint for fetching articles with filtering
- [WebSocket Stream](https://docs.tradingnews.press/api-reference/websocket-stream) — Real-time firehose setup and reconnection patterns

---

> For additional documentation and navigation, see: https://docs.tradingnews.press/llms.txt