# Market news

Market news is what the crypto market is doing now, as Fin follows it: the stories the market is
telling, the latest articles from reviewed publishers, the moves Fin spots as they happen, and
where money is in the market. It is public market data, the same for every user, so your partner
key alone reads it: no user session and no feature to turn on. Every route here only reads, and
reading costs no AI usage; your partner rate limit applies.

A news page takes four calls, and a story page one.

## Stories

```http
GET /v1/market/stories?evidence=reported&limit=50
X-Api-Key: fin_…
```

A story is a few sentences on something happening in the market, written from the articles and the
market figures behind it. The list is most recently confirmed first.

- `topic` is what the story is about, as a reader would file it, one of `markets`, `funds`,
  `regulation`, `legal`, `security`, `governance`, `people`, `deals`, `funding`, `launches`,
  `networks`, `supply`, `stablecoins`, `tokenization`, `economy`, `ai`, `predictions`, `sports`,
  `memecoins`, `defi`, `wallets` and `data`; the reference says what each covers. Fin names it each
  time it writes the story. Show a story by it when nothing it names has a logo of its own; it is
  null for a story last written before topics.
- `status` is `new`, `rising` (gathering coverage), `steady` or `fading`.
- `evidence` is how well it is backed, strongest first: `measured` (a market figure it cites
  moved), `corroborated` (three publishers, or two with an official source), `reported` (an
  official or newsroom source, or two publishers) and `unconfirmed` (one unreviewed source).
- `updatedAt` is when a new source or figure last confirmed it; `firstSeenAt` when Fin first saw it.
- `subjects` are what it is about, each with its `id`, `kind`, `name` and ticker (`symbol`), and
  the listings the desk follows it by: `coingeckoId`, what you read its price history and logo
  with from CoinGecko (a coin's `bitcoin`, a venue's exchange `binance`, a sector's category
  `layer-1`); `hyperliquidCoin` (`BTC`), the coin its Hyperliquid market trades as; and
  `defillamaId`, what DefiLlama lists it as (a venue's or launchpad's protocol `uniswap-v3`, a
  chain's name `Ethereum`), which its logo is found by. Each is null when it has none.
- `sources` are its three newest articles, and `sourceCount` how many it rests on.

Most stories of a day rest on one unreviewed source, so pass `evidence: reported` for a page people
read; `evidence` keeps that grade and every stronger one. `subject` keeps the stories about one
subject: `asset:btc`, `stock:NVDA`, `chain:solana`, `prediction:<slug>` or `market`.

A story is rewritten as its coverage grows, and its figures read the market as it is when you ask,
so read the list again rather than keeping a story for long. A story whose figures can't be read
right now is left out until it is next written, so a page can hold fewer stories than `limit` while
`nextCursor` is set: keep paging until `nextCursor` is null.

## One story

```http
GET /v1/market/stories/{storyId}
X-Api-Key: fin_…
```

The story with every article it rests on, newest first, and two more lists:

- `figures`: each market figure the story states, as it reads now. `label` says what it is in plain
  words (`Price`, `Yes odds`, `Crypto market cap`), `value` and `unit` what it is now, and
  `changePct` how it changed over `window`.
- `moves`: what Fin spotted moving on the story's coins, stocks and markets since the story began,
  newest first, one line per market and kind, as [List market moves](/api-reference/market/moves-list)
  answers them.

A story Fin no longer shows, because its sources were withdrawn or its figures can no longer be
read, answers `404 story_not_found`: take it off your page.

## Headlines

```http
GET /v1/market/headlines?limit=30
X-Api-Key: fin_…
```

The latest articles from reviewed newsrooms and official sources, newest first, each with its
`publisher`, `headline`, `url`, `publishedAt`, a short `excerpt` where the publisher's licence
allows one, and the coins and stocks its headline names (`subjects`, in the order it names them).
Posts, project announcements and unreviewed sites are left out, and so is an article Fin found only
to answer one user's question. An undated article stands at when Fin found it. `subject` keeps the articles naming one coin or stock among the newest 300: recent
coverage, not an archive.

## Moves

```http
GET /v1/market/moves?limit=20
X-Api-Key: fin_…
```

What moved in the market, newest first, each as one plain sentence:

| `kind` | What moved | `text` |
| --- | --- | --- |
| `price` | a coin's price | `WIF up 18.4% in 4 hours` |
| `market` | the market as a whole | `Crypto market cap down 10.5% over 7 days` |
| `odds` | a prediction market's Yes odds | `“Will Bitcoin dip to $71,000 on November 12?” Yes down 13.5 points in 15 minutes` |
| `resolved` | a prediction market resolving | `“Will the price of Bitcoin be between $72,000 and $74,000 on November 12?” resolved` |
| `volume` | a chain's, venue's or launchpad's volume or fees | `Stonks launchpad volume down 31.6% over 30 days` |
| `share` | a launchpad's share of launchpad volume | `pump.fun's share of launchpad volume down 11.6 points over 7 days` |
| `leader` | a new leader of a leaderboard | `pump.fun takes the lead from Montra in 7-day launchpad volume` |
| `entrant` | a newcomer to a top list | `LaunchLab enters the top 5 launchpads by 7-day volume at #3` |

`changePct` (a price, market or volume move) or `changePoints` (odds and shares) is the move's
exact size and `window` its span, for drawing your own label. `subjects` are what moved, the one
the sentence is about first. Each market has one line per kind, and each leaderboard one line of
lead changes: a newer move on the same line replaces the older one, so a prediction market whose
odds swing every quarter hour stays one line, and a lead that changes back leaves only the latest
change. Narrow the list with `kind` or `subject` (the latest of each line among the moves naming
it), and read the first page again to follow it: a newer move has a larger `id`. A move Fin can't
put into words is left out, so a page can hold fewer moves than `limit` while `nextCursor` is set:
keep paging until `nextCursor` is null.

## Money flows

```http
GET /v1/market/flows
X-Api-Key: fin_…
```

Six market-wide figures, each with its value in US dollars and its change over a day, a week and a
month: the crypto market cap, alt trading volume, perps open interest, stablecoin supply, DEX
trading volume and launchpad volume. A volume's `valueUsd` is the latest day's total, and its
change compares each window with the one before; a level's change compares the window's end with
its start. A figure Fin doesn't have right now is left out, and a change without enough history
is null.

## A news page

1. Stories with `evidence: reported`, up to 100: keep those updated in the last two days and order
   them as your page needs, for example the best backed and most active first.
2. Headlines: the newest 30.
3. Moves: the newest 20.
4. Flows: all of them.

Read them again every minute or so while the page is open, and open a story with
[Get a market story](/api-reference/market/stories-get).
Label the stories as written by AI, show their sources beside them, and say the news is not
investment advice.

## Paging and refusals

The lists take `limit` (up to 100) and `cursor`. Pass `nextCursor` back unchanged. A stories or
headlines cursor is good only with the filters it came with; a moves cursor is a place in the list,
good with any filters. A stories or moves page can hold fewer rows than `limit` while `nextCursor`
is set, so keep paging until `nextCursor` is null.

| Answer | Why |
| --- | --- |
| `400 invalid_cursor` | The cursor is not one this list issued, or a stories or headlines cursor came with other filters. |
| `404 story_not_found` | No story with this id is current. |
