Guides

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 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:

kindWhat movedtext
pricea coin's priceWIF up 18.4% in 4 hours
marketthe market as a wholeCrypto market cap down 10.5% over 7 days
oddsa prediction market's Yes odds“Will Bitcoin dip to $71,000 on November 12?” Yes down 13.5 points in 15 minutes
resolveda prediction market resolving“Will the price of Bitcoin be between $72,000 and $74,000 on November 12?” resolved
volumea chain's, venue's or launchpad's volume or feesStonks launchpad volume down 31.6% over 30 days
sharea launchpad's share of launchpad volumepump.fun's share of launchpad volume down 11.6 points over 7 days
leadera new leader of a leaderboardpump.fun takes the lead from Montra in 7-day launchpad volume
entranta newcomer to a top listLaunchLab 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. 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.

AnswerWhy
400 invalid_cursorThe cursor is not one this list issued, or a stories or headlines cursor came with other filters.
404 story_not_foundNo story with this id is current.
Fin documentation Built from the API contract · v1

Search all documentation