# EventTrader Headlines API

Every headline our news engine ingests (press wires, SEC EDGAR, Google News deal searches, Yahoo Finance symbol news, crypto news), each with topic tags, tickers, sector, a sentiment score where our AI scorer has scored it, and the stated deal size of M&A headlines. REST list with filters and a WebSocket that pushes each new headline as it goes public.

Product page: https://cymetica.com/headlines-api · API description (no key): https://cymetica.com/api/v1/headlines-api · Free delayed sample (no key): https://cymetica.com/api/v1/headlines-api/sample

## Access: paid NEXUS plan required

| Plan | Price a month (USDC) | Headlines API |
|---|---|---|
| Free | $0.00 | no |
| Pro | $20.00 | yes |
| Max 5x | $100.00 | yes |
| Max 20x | $200.00 | yes |

Pick a plan at https://cymetica.com/usage. Send your API key as `X-API-Key` (create one at https://cymetica.com/account, or `POST https://cymetica.com/mcp/v1/register`). No key: 401. Key without a paid plan: 402 with `detail.code` = `PAID_PLAN_REQUIRED` and `detail.plans_url`. Plan check failing: 503 (access denied until it works).

## REST

`GET https://cymetica.com/api/v1/headlines-api/headlines` — newest first. Parameters: `limit` (1-200, default 50; over 200 is a 422 naming the maximum), `cursor` (the `next_cursor` of the last page), `since_id`, `from` / `to` (ISO 8601 on published_at), `source`, `ticker` (comma list, max 20), `topic` (ma | stocks | crypto | global), `sector` (aerospace_defense | crypto | technology | energy | finance | healthcare | automotive | materials | real_estate | media_telecom | consumer | agriculture), `lang` (en | und), `min_sentiment` / `max_sentiment` (-1..1). Response: `items`, `count`, `limit`, `max_limit`, `next_cursor`, `filters`.

## Stream

`wss://cymetica.com/ws/headlines-api?api_key=<key>` (or the `X-API-Key` header). Optional `topic`, `sector`, `ticker`, `source` query filters. Frames: `subscribed`, `headline` (`data` = one item, `delivered_at`), `event_card` (a card was made from a headline), `retract` (ids hidden as near-duplicates), `heartbeat` every 30 s. Refusals: an `error` frame, then close 4401 / 4402 / 4503 / 4429 / 4422. A headline is pushed when it goes public (after our asset model has read it, usually well under a minute after ingestion). After a disconnect, catch up with `since_id`.

## Fields

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Stable headline id. Ids grow in ingestion order; use it as since_id / cursor. |
| `title` | string | The headline as published by the source (a Google News title has its publisher suffix moved to `source`). |
| `url` | string|null | Link to the original article. We do not redistribute the article body. |
| `source` | string | Publisher or feed name, e.g. PR Newswire, GlobeNewswire, SEC EDGAR, Coinpedia; `Wire` for aggregated wires. |
| `published_at` | string (ISO 8601, UTC offset) | The source's own timestamp. |
| `ingested_at` | string (ISO 8601, UTC offset) | When our engine picked the headline up. |
| `language` | string|null | Detected language code; the feed carries `en` and `und` (undetermined) only. |
| `topics` | array of string | Rule-based topic tags, any of: ma (merger or acquisition language), stocks, crypto, global (world events). Never empty. |
| `tickers` | array of string | Stock or crypto symbols attached by the source or found in the title. Often empty. |
| `deal_value_usd` | number|null | Deal size stated in an M&A headline's own text, in USD. Null when no deal size is stated. |
| `sector` | string|null | Sector key from the Event Card sector rules applied to the title: aerospace_defense, crypto, technology, energy, finance, healthcare, automotive, materials, real_estate, media_telecom, consumer, agriculture. Keyword rules, not an industry registry. Null when the title names no sector. |
| `sector_label` | string|null | Human name of `sector`, e.g. "Healthcare & Biotech". |
| `sentiment_score` | number|null | -1.0 (most bearish) to +1.0 (most bullish); 0 is neutral. Set by our AI headline scorer for the headlines it has scored; the sign is the direction. Null when not scored. |
| `sentiment_status` | string | `scored` or `not_scored`. Most headlines are not scored; see coverage. |
| `price_moves_pct` | object | {SYMBOL: % price move since the headline's time} for the headline's tickers, refreshed by the price worker. Empty until computed. |
| `event_card` | object|null | {id, url} of the Event Card made from this headline, if one exists. |
| `actions` | object | {make_event_card: the POST path that turns this headline into an Event Card}. |

## Coverage, last 24 hours (1080 headlines)

- sentiment_score: 0.9% of headlines (the rest are `not_scored`)
- sector: 33.5%
- tickers: 16.8%
- topics: 100.0%
- deal_value_usd: 1.9%
- price_moves_pct: 16.7%
- event card already made: 0.0%

## Make an Event Card

`POST https://cymetica.com/api/v1/headlines-api/headlines/{id}/event-card` with your key. Uses the pipeline that cards the feed automatically: our asset model picks a basket and a quality gate refuses baskets that are too thin. One card per headline. Answers: `exists` (200, the card), `created` (201, public at once: no review step on this path), `pending` (202, poll `GET` on the same path), `refused` (200, with `reason` and `retry_after`). Asking again never makes a duplicate. No fee is charged, nothing is traded, nothing is deployed on-chain. Up to 10 new builds an hour per account.

## Limits

60 REST requests a minute per account; 3 stream connections per account; 10 event-card builds an hour. 429 with `Retry-After` when exceeded.

## What it does not do

- No article bodies or summaries: title, link, source name and our own tags and scores only.
- English only (other languages are filtered out of the feed).
- Sentiment is not on every headline; sector comes from keyword rules on the title, not an industry registry.
- Not investment advice.

## MCP

`https://cymetica.com/mcp/v1` tools: `get_headlines_api_info` and `get_headlines_sample` (no plan), `search_headlines_api` and `headline_event_card` (the agent's linked account needs a paid plan).