# 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

```http
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

```http
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. Adding `market` is not necessary to
  request news for one asset.
- **`mode: "auto"`**, the default when omitted, may answer `200` at once with `status: ready` when
  every subject barely moved: Fin's own words and figures, no research and no model cost.
- **A researched scope** answers `202` with `status: generating`. Read it with
  [Get a market brief](/api-reference/market/briefs-get) after `retryAfterSeconds` until it is
  `ready` or `failed`. 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

```jsonc
{
  "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": "…" }]
}
```

- `magnitude` compares the 24-hour price move with the subject's usual daily move: `quiet`,
  `notable` or `large`. A move under a quarter of a percent is always `quiet`, so a stablecoin's
  daily wiggle is no news, while its slip to 0.996 is.
- `metrics[].name` can grow: show the names you know and skip the rest.
- `research.performed: false` with `skipReason: "quiet"` means no news search ran. Empty sources
  here do not mean that no news exists. Per-subject `searchStatus` distinguishes `not_searched`,
  `complete`, `partial` and `unavailable`; `complete` means the planned searches finished, not that
  every possible publisher was searched. `explanationStatus` separately distinguishes a
  `possible_driver`, `context_only` and an `unexplained` move. `sourceIds` names 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.
  `ready` can include `partial` or `unavailable` research 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 `unit` is `usd` or `percent`. Price, volume, market cap and TVL are USD;
  dominance and `changePct` are percentages. Negative changes are declines. `market` measures total
  crypto capitalization and BTC dominance, while BTC price is a separate asset and benchmark.
- `provenance` names the provider and reference identity. Its `comparison.start` and `end` carry
  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.
- `asOf` and `generatedAt` serve different purposes. `provenance.observedAt` is the provider's
  timestamp, or null if unavailable. `asOfBasis` tells whether `asOf` is 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`, `window` and effective `mode`. 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.
