Market briefs
A market brief explains what part of the market did over the past day, and why, with the sources behind each reason. Ask about the whole crypto market, a chain, an asset, one chain's copy of an asset, a stock, or up to ten of these together. No user is involved: your partner key alone calls these routes, once an operator turns market briefs on for your key.
Every figure in a brief is Fin's own. An asset's or a chain's price, change and usual daily move come from the prices Fin's market desk publishes. A stock's and one chain's copy of an asset come from Fin's own price records of the token traded, the trading venue's price. Market cap, volume, dominance and value locked come from the desk's market reads. The model writes the words, and Fin checks them before you see them: no figure, link or advice of their own, and every reason cites evidence returned during the research. Reasons are possible explanations, not proof of causality. explained describes the brief as a whole; use research.coverage to see what the search and explanation supported for each subject.
Find the subjects
GET /v1/market/subjects?alias=usd-coin
X-Api-Key: fin_…| Subject | What it is | Example |
|---|---|---|
market | the whole crypto market | market |
chain:<chain> | a chain and its ecosystem | chain:solana |
asset:<asset> | an asset across every chain | asset:usdc |
asset:<asset>@<chain> | that asset's copy on one chain | asset:usdc@solana |
stock:<ticker> | a U.S. stock or ETF | stock:NVDA |
Subject ids are Fin's own. Pass alias with a CoinGecko id, a symbol, a contract address or a 1Click asset id to find the subjects it names, or kind to list one kind. An asset spans its listed chain copies, and its price is the market desk's USD price of its one CoinGecko asset rather than a blend across chains: asset:near is priced as wrapped NEAR, and chain:near shares its native coin's price. A copy on one chain, such as asset:usdc@solana, is measured from its own token, so a bridged copy that loses its peg shows its own move. A stock uses its reviewed tokenized reference. A price metric's provenance names the CoinGecko asset, and for a copy or a stock the reference token measured. The usual daily move needs at least twenty daily moves in the past thirty days; with fewer, it and magnitude are null.
Create a brief
POST /v1/market/briefs
X-Api-Key: fin_…
Idempotency-Key: 6f1c2a7e-…
{ "scope": ["chain:solana", "asset:sol"], "window": "24h", "mode": "news" }mode: "news"researches the requested subjects even when their prices barely moved. Use it when a reader opens news or asks what happened to an asset. Addingmarketis not necessary to request news for one asset.mode: "auto", the default when omitted, may answer200at once withstatus: readywhen every subject barely moved: Fin's own words and figures, no research and no model cost.- A researched scope answers
202withstatus: generating. Read it with Get a market brief afterretryAfterSecondsuntil it isreadyorfailed. The wait depends on the research and checks required.
The same key with the same request returns the same job; omitted mode and auto are equivalent. Changing scope, window or effective mode under that key is refused 409 request_key_conflict. Each researched brief uses model runs your partner owns: it is charged to your partner's AI usage, counts toward your partner's day and month spend caps and active-run limit like every other run of yours, and the job's costCents says what it cost once it finished. Partner usage reports it in partnerRunTotals.
Read a brief
{
"headline": "Solana falls after its network halted",
"summary": "Solana dropped as validators stopped producing blocks.",
"explained": true,
"moves": [
{ "subject": "asset:sol", "magnitude": "large",
"metrics": [{ "name": "price", "value": "88", "changePct": "-12", "asOf": "…",
"benchmark": { "subject": "asset:btc", "changePct": "-1" } }] }
],
"drivers": [{ "text": "Validators halted block production after a consensus bug.",
"subjects": ["asset:sol", "chain:solana"], "sourceIds": ["src_1"] }],
"sources": [{ "id": "src_1", "title": "…", "publisher": "coindesk.com", "url": "…", "publishedAt": "…" }]
}
magnitudecompares the 24-hour price move with the subject's usual daily move:quiet,notableorlarge. A move under a quarter of a percent is alwaysquiet, so a stablecoin's daily wiggle is no news, while its slip to 0.996 is.metrics[].namecan grow: show the names you know and skip the rest.research.performed: falsewithskipReason: "quiet"means no news search ran. Empty sources here do not mean that no news exists. Per-subjectsearchStatusdistinguishesnot_searched,complete,partialandunavailable;completemeans the planned searches finished, not that every possible publisher was searched.explanationStatusseparately distinguishes apossible_driver,context_onlyand anunexplainedmove.sourceIdsnames the supporting cited sources. A complete search can still leave the move unexplained. The single correction receives feedback for rejected fields and is independently reviewed again; supported context is not automatically approved for publication.readycan includepartialorunavailableresearch with a cautious abstention; it means the checked pipeline finished, not that news retrieval succeeded. Surface that coverage to readers rather than presenting an empty source list as proof that no relevant news exists.- Each driver needs supporting official, permitted or newsroom reporting. Unreviewed items and press releases alone are leads, so Fin does not publish their claims as drivers. Publication time does not establish event time: a recent article about an older event can provide context, but cannot by itself establish a current explanation. The prompt revision is recorded in
pipelineVersion; earlier jobs retain their recorded revision. - A metric's optional
unitisusdorpercent. Price, volume, market cap and TVL are USD; dominance andchangePctare percentages. Negative changes are declines.marketmeasures total crypto capitalization and BTC dominance, while BTC price is a separate asset and benchmark. provenancenames the provider and reference identity. Itscomparison.startandendcarry the exact prices and observation times used for a calculated return; these endpoints can span slightly more or less than 24 hours. A provider-reported change has no reconstructed endpoints; its reported trailing period does not create exact observations at the job's window boundaries. A benchmark can carry its own provenance because its observation times may differ.asOfandgeneratedAtserve different purposes.provenance.observedAtis the provider's timestamp, or null if unavailable.asOfBasistells whetherasOfis a provider observation, retrieval time or generation time. A fresh generation or cache read does not refresh an old observation. Price facts are captured when requested; research metrics can be read later. The narrative review receives the compiled research metrics as well as the captured price facts, so a missing asset-style price does not hide an available market-wide level or change.- Research/provenance fields may be absent on older jobs. A missing value remains unavailable; it is never evidence for zero movement, zero volume or no relevant news. Source publishers may be null, so retain a fallback label when rendering citations.
- Fin keeps no cache and serves each job only to the key that created it. Cache a brief on your side, keyed by its normalized
scope,windowand effectivemode. Share creation keys and pending state across replicas if you need duplicate-cost protection across restarts. Reuse the original creation key after transport uncertainty; starting a new key can incur another model cost.
Show it
Label a brief as written by AI, show its sources beside it, and say that it is not investment advice.
When a brief cannot be made
| Answer | Why |
|---|---|
400 scope_invalid | A subject is not a subject id, or appears twice. |
404 subject_unsupported | A subject is not one market briefs cover. |
403 market_briefs_disabled | Market briefs are not turned on for your key. |
429 briefs_busy | Your partner is at its active-run limit; retry after Retry-After. |
429 budget_exhausted | Your partner's AI budget is used up until the next day or month. |
failed with generation_failed | The brief could not be completed; consult optional failure details before retrying. |
failed with brief_invalid | The research produced words that failed Fin's checks twice. |
Optional failure.details contains a safe stage, reason and retryable flag. It never contains provider error prose. Stages are admission, research, synthesis, validation or deadline; reasons are unavailable, invalid_output, budget_exhausted or deadline_exceeded. A deliberate retry after a terminal failure uses a new Idempotency-Key and may incur another cost. Reusing the old key still returns its original failed job. Do not automatically create another job after a lost response or while the first job is generating.
Evidence and bounded correction
Fin searches each canonical news identity within the job's absolute window. News identity and price reference identity can differ: NEAR Protocol research does not search only for wNEAR. A subject search makes at most two provider searches and two shortlisted content lookups. Provider raw content is relayed only for reviewed excerpt-permitted publishers; other items remain title_only. This is provider-relayed evidence, not a claim that Fin independently opened an original article. Sources retain publishedAtBasis, retrievedAt, eventAt, sourceKind, evidenceLevel and a bounded permitted excerpt when available. Unknown event time remains null.
An independent, tool-free model review evaluates the headline, summary and every driver against committed passages. evidence on a brief and driver carries exact short quote witnesses. Driver classification separates context from qualified possible drivers; eventAt requires an actual source-supported event inside the window. A publication timestamp alone is insufficient. Exact quotes constrain this assistive review but cannot prove semantic truth or market causality. When there are no supported drivers, Fin uses cautious server-written abstention text.
The public limits remain headline 120, summary 600 and driver 300 JavaScript string code units. A completed candidate that exceeds them can receive one tool-free correction against its original facts and evidence; Fin does not truncate the words or run the research again. The evidence review and correction both consume partner model usage, included in costCents. Unknown dispatched accounting is reported as null rather than zero. The job has a thirty-minute recovery deadline; this bounds job recovery, not promised response time. Work already admitted retains its normal run deadline and may settle later; an unknown cost stays null. Reuse the same key after a transport failure.