{"openapi":"3.0.3","info":{"title":"PreReason API","version":"1.0.0","description":"PreReason returns market briefings with the interpretation already done:\ntrends, regime classification and confidence scores, in place of\nraw numbers. Markdown by default, which costs about\n40 percent fewer tokens than JSON. Add ?format=json for structured output.\n\nCoverage is macro, rates, bonds, FX, commodities, listed companies and\nBitcoin: the Fed balance sheet, M2, net liquidity, Treasury yields and\nauctions, the dollar, oil and gas inventories, metals and grains, company\nbriefings, Bitcoin price, network and ETF flows, and cross asset\ncorrelations.\nGET /api/briefings is the live catalogue, with the tier each briefing\nneeds, and GET /api/metrics lists the individual series. Neither needs a key.\n\nNot every endpoint needs one. Each operation below declares its own rule,\nand the catalogue endpoints, the health and status endpoints and POST\n/api/mcp are open. A briefing needs either an API key, sent as\nAuthorization: Bearer or X-API-Key, or a payment for that single call:\nrequest a priced endpoint without a key and the 402 quotes both x402 and\nMPP, USDC on Base. Free keys at https://www.prereason.com/signup, and an\nagent with no browser of its own can earn one through the claim flow at\nhttps://www.prereason.com/auth.md. Full reference at\nhttps://www.prereason.com/docs.\n\nBriefings are built from these providers' data: Federal Reserve Bank of\nNew York, Board of Governors of the Federal Reserve System, U.S. Department\nof the Treasury, Treasury International Capital (TIC), U.S. Treasury Fiscal\nData, CFTC, EIA, BIS, SEC EDGAR, FRED, mempool.space and CoinGecko, and 21\nmore, each named with every value it supplies (every provider is listed at\nhttps://www.prereason.com/data-sources). Freshness ranges from near real\ntime to monthly depending on the series, and ETF market data updates every\n15 minutes during market hours. Powered by CoinGecko. This product uses the\nFRED API but is not endorsed or certified by the\nFederal Reserve Bank of St. Louis.\n","contact":{"name":"API Support","url":"https://www.prereason.com/docs","email":"support@prereason.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"x-guidance":"Pay per request with no account. Call a priced GET endpoint and read the 402: it offers MPP (WWW-Authenticate: Payment, method evm, USDC on Base) and x402 (PAYMENT-REQUIRED, USDC on Base or Solana). Pay with either and retry the same request carrying the credential. With an API key (X-API-Key) the same endpoints are served under your plan instead. Start with GET /api/btc ($0.02) for a Bitcoin briefing; /api/macro, /api/cross/regime and /api/fx cover macro, market regime and FX liquidity. Responses are markdown by default; add ?format=json for structured output."},"servers":[{"url":"https://api.prereason.com","description":"Production API"}],"x-service-info":{"name":"PreReason","url":"https://api.prereason.com","documentation":"https://www.prereason.com/docs","category":"financial-data","audience":"ai-agents","manifest":"https://api.prereason.com/.well-known/mpp","categories":["data"],"docs":{"homepage":"https://www.prereason.com","apiReference":"https://www.prereason.com/docs","llms":"https://www.prereason.com/llms.txt"}},"x-payment-info":{"mppVersion":"1.0","intents":["charge"],"protocol":"x402-v2","methods":[{"id":"x402.exact.evm","kind":"crypto","scheme":"exact","asset":"USDC","networks":["eip155:8453","eip155:84532"]},{"id":"x402.exact.svm","kind":"crypto","scheme":"exact","asset":"USDC","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"]}],"pricing":{"free":"$0.02","basic":"$0.03","pro":"$0.05"},"mpp":{"method":"evm","intent":"charge","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6,"realm":"api.prereason.com","challengeHeader":"WWW-Authenticate","credentialHeader":"Authorization","receiptHeader":"Payment-Receipt"},"challenge":{"bodyHeader":"PAYMENT-REQUIRED","legacyBodyHeader":"X-Payment-Requirements","bodyCarriesQuote":"unpaid-requests-only","paymentHeaders":["payment-signature","x-payment"],"preferredPaymentHeader":"payment-signature"},"manifest":"https://api.prereason.com/.well-known/mpp","references":{"spec":"https://mpp.dev","ietfDraft":"https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/","stripeDocs":"https://docs.stripe.com/payments/machine/mpp"}},"tags":[{"name":"Context","description":"Briefing-based context endpoints. The primary way to consume PreReason data.\nEach briefing bundles related metrics with trend analysis and confidence scores.\n"},{"name":"Metrics","description":"Individual metric data with trend analysis and interpretation"},{"name":"Treasury Holdings","description":"Per-company corporate Bitcoin treasury holdings with provenance.\nThe btc.treasury briefing interprets and ranks the top holders; these\nendpoints are the lookup surface for every tracked company, with the\nsource, as-of date and filing URL attached to each figure.\n"},{"name":"Company Briefings","description":"One listed company's briefing bought per call, whole or one block at a\ntime, for a company of a market that is live. A key reads the same\nbriefing through GET /api/context when its plan reaches the market.\n"},{"name":"Webhooks","description":"Change events, pushed by webhook to an account's registered addresses or\nread from the feed. What changed since a cursor: a live briefing's state label, a tracked\nrelease, and, for the companies a read names, newer figures, an event\ndriven situation turning on, and filed news. A key on the\nBasic or Pro plan reads its plan's events; a caller with no key pays\nper read.\n"},{"name":"Short URLs","description":"Convenience aliases that forward to context briefings. Same auth, same response.\nUse these for quick access or human-friendly URLs.\n"},{"name":"System","description":"Health, status, and version endpoints"},{"name":"Agent access","description":"How an agent with no key gets one from inside its own session. The agent\ncreates a claim, shows one link to the human who owns it, and polls until\nthe human has signed in and approved; the key it then receives belongs to\nthat human's account. No key is issued without the approval. The MCP\nbridge (npx -y @prereason/mcp) runs the same flow for an MCP client; the\nhosted MCP server hands out no key.\n"}],"paths":{"/api/btc":{"get":{"tags":["Short URLs"],"summary":"BTC Quick Check","description":"Alias for `GET /api/context?briefing=btc.quick-check`. Free tier.","operationId":"shortBtc","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Quick Check","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.quick-check context"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/btc/context":{"get":{"tags":["Short URLs"],"summary":"BTC Full Context","description":"Alias for `GET /api/context?briefing=btc.context`. Free tier.","operationId":"shortBtcContext","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Full Context","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.context data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/pulse":{"get":{"tags":["Short URLs"],"summary":"BTC Pulse","description":"Alias for `GET /api/context?briefing=btc.pulse`. Free tier.","operationId":"shortBtcPulse","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Pulse","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.pulse data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/grid":{"get":{"tags":["Short URLs"],"summary":"BTC Grid Stress","description":"Alias for `GET /api/context?briefing=btc.grid-stress`. Free tier.","operationId":"shortBtcGrid","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Grid Stress","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.grid-stress data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/momentum":{"get":{"tags":["Short URLs"],"summary":"BTC Momentum","description":"Alias for `GET /api/context?briefing=btc.momentum`. Basic tier.","operationId":"shortBtcMomentum","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Momentum","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.momentum data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/onchain":{"get":{"tags":["Short URLs"],"summary":"BTC On-Chain","description":"Alias for `GET /api/context?briefing=btc.on-chain`. Basic tier.","operationId":"shortBtcOnchain","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC On-Chain","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.on-chain data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/miners":{"get":{"tags":["Short URLs"],"summary":"BTC Miner Survival","description":"Alias for `GET /api/context?briefing=btc.miner-survival`. Basic tier.","operationId":"shortBtcMiners","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Miner Survival","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.miner-survival data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/etf":{"get":{"tags":["Short URLs"],"summary":"BTC ETF Flows","description":"Alias for `GET /api/context?briefing=btc.etf-flows`. Basic tier.","operationId":"shortBtcEtf","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC ETF Flows","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.etf-flows data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/full":{"get":{"tags":["Short URLs"],"summary":"BTC Full Analysis","description":"Alias for `GET /api/context?briefing=btc.full`. Pro tier.","operationId":"shortBtcFull","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Full Analysis","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.full data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/factors":{"get":{"tags":["Short URLs"],"summary":"BTC Factors","description":"Alias for `GET /api/context?briefing=btc.factors`. Pro tier.","operationId":"shortBtcFactors","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Factors","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.factors data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/energy":{"get":{"tags":["Short URLs"],"summary":"BTC Energy","description":"Alias for `GET /api/context?briefing=btc.energy`. Pro tier.","operationId":"shortBtcEnergy","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Energy","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.energy data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/btc/treasury":{"get":{"tags":["Short URLs"],"summary":"BTC Treasury Holdings","description":"Alias for `GET /api/context?briefing=btc.treasury`. Pro tier.","operationId":"shortBtcTreasury","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"BTC Treasury Holdings","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"btc.treasury data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/macro":{"get":{"tags":["Short URLs"],"summary":"Macro Snapshot","description":"Alias for `GET /api/context?briefing=macro.snapshot`. Free tier.","operationId":"shortMacro","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Macro Snapshot","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"macro.snapshot data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/macro/liquidity":{"get":{"tags":["Short URLs"],"summary":"Macro Liquidity","description":"Alias for `GET /api/context?briefing=macro.liquidity`. Basic tier.","operationId":"shortMacroLiquidity","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Macro Liquidity","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"macro.liquidity data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/macro/rates":{"get":{"tags":["Short URLs"],"summary":"Yield Curve and Breakeven Inflation","description":"Alias for `GET /api/context?briefing=macro.rates`. Pro tier.","operationId":"shortMacroRates","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Yield Curve and Breakeven Inflation","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"macro.rates data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/cross/correlations":{"get":{"tags":["Short URLs"],"summary":"Cross-Asset Correlations","description":"Alias for `GET /api/context?briefing=cross.correlations`. Free tier.","operationId":"shortCrossCorrelations","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Cross-Asset Correlations","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"cross.correlations data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/cross/breadth":{"get":{"tags":["Short URLs"],"summary":"Market Breadth","description":"Alias for `GET /api/context?briefing=cross.breadth`. Basic tier.","operationId":"shortCrossBreadth","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Market Breadth","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"cross.breadth data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/cross/regime":{"get":{"tags":["Short URLs"],"summary":"Regime Detection","description":"Alias for `GET /api/context?briefing=cross.regime`. Pro tier. `regime.current_regime` is `expansion`, `contraction` or `transition`; through 2026-12-31 the name it had before 2026-10-01 (`risk_on_expansion`, `risk_off_contraction`) is served beside it as `regime.current_regime_legacy`.","operationId":"shortCrossRegime","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Regime Detection","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"cross.regime data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/fx":{"get":{"tags":["Short URLs"],"summary":"FX Liquidity","description":"Alias for `GET /api/context?briefing=fx.liquidity`. Pro tier.","operationId":"shortFx","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"FX Liquidity","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"fx.liquidity data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/treasuries":{"get":{"tags":["Treasury Holdings"],"summary":"All tracked corporate BTC treasury holdings","description":"Every tracked company with its holding, source and as-of date. Pro tier.\n\n**Precision is not uniform, and the response says so per row.**\nA figure the company filed with the SEC is public record: `precision` is\n`exact`, `btc_exact` carries the number, and `filing_url` links the\ndocument. A figure published by CoinGecko is an estimate: `precision` is\n`estimate`, `btc_exact` is `null`, and only the rounded `btc_display` is\ngiven. Reading `btc_exact` alone can never mistake an estimate for a\nfiled figure.\n\nWhere our two sources disagreed materially, someone read the filing and\nthe verdict appears in `adjudication` with its evidence.\n\nRows do not sum to `total_btc_exact`, because estimate rows are rounded.\nThe roster is a curated subset of listed treasury holders, so the total\nunderstates the market-wide figure.\n\n**Financing, from filings.** Each row carries `financing_summary`, or\n`null`: the senior claims the company's own latest periodic SEC filing\nstates (debt principal plus preferred stock at its liquidation\npreference), the same figure per BTC in that filing, the bitcoin's share\nof total assets and what falls due within 24 months, each as of the\nfiling's balance sheet date and with the filing's link. These are filed\nfigures, served exact, and they keep their own date: the holding beside\nthem may be newer. `financing.companies_with_filed_financing` counts the\nrows that carry one. A company that files in yen on EDINET (Metaplanet)\nis in dollars like the rest, converted at one stored rate of its\nbalance sheet date; its summary's `filed_currency` carries its senior\nclaims as filed in yen and that rate with its source and date\n(`filed_currency` is `null` for a company that files in dollars), and\nits summary's `citation` carries EDINET's source citation under the\nPublic Data License 1.0, as EDINET's terms ask (`null` for an SEC\nfiler).\n\n**mNAV.** Each row carries `mnav_summary`, or `null`: market value\nover the value of the bitcoin held, as `value`, with its `basis` and\nits `as_of` date. The basis is `in house` (derived from the company's\nfiled share count, a stored share close and the served holding) or,\nfor a company with no in house figure, `CoinGecko` (CoinGecko's own\npublished figure, named as CoinGecko's). The two are computed\ndifferently and are not comparable to the hundredth. A figure is shown\nonly where the bitcoin is worth at least a tenth of the market value\n(10 or less), and a CoinGecko figure only at 0.25 or more.\n`mnav.companies_with_mnav` counts the rows that carry\none, and the company route carries the inputs or the reason.\n\n**Withheld.** `withheld` lists the tracked companies whose count from\nour source is above the total the company itself reported, and those\nwhose count PreReason read from a filing does not match that filing,\neach with `ticker`, `company_name`, `reason` and `evidence_filing` (the\nfiling the reason cites: `form`, `accession`, `filed`, `url`). None of\nthem is in `holdings` or in `total_btc_exact`, and no count is shown\nfor them. It is an empty list when none is withheld.\n","operationId":"listTreasuryHoldings","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"All tracked corporate BTC treasury holdings","intent":"charge","method":"evm"}]},"responses":{"200":{"description":"Holdings for every tracked company"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Requires Pro or Enterprise tier"},"503":{"description":"Treasury holdings temporarily unavailable"}}}},"/api/cross/ai-compute":{"get":{"tags":["Short URLs"],"summary":"AI Compute and Power Chain","description":"Alias for `GET /api/context?briefing=cross.ai-compute`. Pro tier.","operationId":"shortCrossAiCompute","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"AI Compute and Power Chain","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"cross.ai-compute data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/energy-basket":{"get":{"tags":["Short URLs"],"summary":"Energy Basket","description":"Alias for `GET /api/context?briefing=commodities.energy-basket`. Pro tier.","operationId":"shortCommoditiesEnergyBasket","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Energy Basket","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.energy-basket data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/macro/auctions":{"get":{"tags":["Short URLs"],"summary":"Treasury Auction Calendar and Dynamics","description":"Alias for `GET /api/context?briefing=macro.auctions`. Basic tier.","operationId":"shortMacroAuctions","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Treasury Auction Calendar and Dynamics","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"macro.auctions data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/macro/calendar":{"get":{"tags":["Short URLs"],"summary":"Macro Calendar: Releases, Decisions and Auctions","description":"Alias for `GET /api/context?briefing=macro.calendar`. Basic tier.","operationId":"shortMacroCalendar","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Macro Calendar: Releases, Decisions and Auctions","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"macro.calendar data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/bonds/context":{"get":{"tags":["Short URLs"],"summary":"US Treasury Holders: Short Form","description":"Alias for `GET /api/context?briefing=bonds.context`. Basic tier.","operationId":"shortBondsContext","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"US Treasury Holders: Short Form","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"bonds.context data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/bonds/full":{"get":{"tags":["Short URLs"],"summary":"US Treasury Holders","description":"Alias for `GET /api/context?briefing=bonds.full`. Pro tier.","operationId":"shortBondsFull","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"US Treasury Holders","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"bonds.full data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/eth/context":{"get":{"tags":["Short URLs"],"summary":"Ethereum Context","description":"Alias for `GET /api/context?briefing=eth.context`. Basic tier.","operationId":"shortEthContext","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Ethereum Context","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"eth.context data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/gold":{"get":{"tags":["Short URLs"],"summary":"Commodities Gold","description":"Alias for `GET /api/context?briefing=commodities.gold`. Basic tier.","operationId":"shortCommoditiesGold","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Commodities Gold","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.gold data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/silver":{"get":{"tags":["Short URLs"],"summary":"Commodities Silver","description":"Alias for `GET /api/context?briefing=commodities.silver`. Basic tier.","operationId":"shortCommoditiesSilver","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Commodities Silver","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.silver data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/copper":{"get":{"tags":["Short URLs"],"summary":"Commodities Copper","description":"Alias for `GET /api/context?briefing=commodities.copper`. Basic tier.","operationId":"shortCommoditiesCopper","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Commodities Copper","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.copper data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/wheat":{"get":{"tags":["Short URLs"],"summary":"Commodities Wheat","description":"Alias for `GET /api/context?briefing=commodities.wheat`. Basic tier.","operationId":"shortCommoditiesWheat","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"30000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Commodities Wheat","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.wheat data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/oil-producers":{"get":{"tags":["Short URLs"],"summary":"Oil and Its Producers","description":"Alias for `GET /api/context?briefing=commodities.oil-producers`. Pro tier.","operationId":"shortCommoditiesOilProducers","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Oil and Its Producers","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.oil-producers data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/gold-miners":{"get":{"tags":["Short URLs"],"summary":"Gold and the Miners","description":"Alias for `GET /api/context?briefing=commodities.gold-miners`. Pro tier.","operationId":"shortCommoditiesGoldMiners","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Gold and the Miners","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.gold-miners data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/commodities/grains-agribusiness":{"get":{"tags":["Short URLs"],"summary":"Grains and Agribusiness","description":"Alias for `GET /api/context?briefing=commodities.grains-agribusiness`. Pro tier.","operationId":"shortCommoditiesGrainsAgribusiness","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Grains and Agribusiness","intent":"charge","method":"evm"}]},"parameters":[{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"commodities.grains-agribusiness data"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/treasuries/{ticker}":{"get":{"tags":["Treasury Holdings"],"summary":"One company's BTC treasury holding","description":"Single-company lookup with the same precision and provenance rules as\nthe list endpoint. Pro tier.\n\nA 404 means the company is not on the tracked roster. It is **not**\nevidence that the company holds no Bitcoin.\n\nA withheld company (the list's `withheld`) answers 200 with `holding:\nnull` and `withheld` (its reason and the filing the reason cites), its\n`financing` as below, and no `mnav`.\n\n`financing` carries what the company's own latest periodic SEC filing\nstates, as of its balance sheet date: debt by instrument, preferred\nclasses at their liquidation preference, the maturity table, the\nbitcoin count in the same filing, the senior claims these add up to,\nand the financing filings made since, which are listed and never added\nin. It is `null`, with `financing_note` saying why, for a company with\nno SEC filing, or with no filing reading served (none is stored, or\nits newest is held for review).\n\nA company that files in yen is read from its own annual or half year\nreport on EDINET (Metaplanet). Its `financing` has the same shape, in\ndollars: every figure is the filed yen amount converted at one stored\nrate, the Federal Reserve Board's H.10 rate of the balance sheet date.\n`financing.filed_currency` carries that rate with its source and date\nand every amount as filed in yen (`null` for a company that files in\ndollars), and `financing.citation` carries EDINET's source citation\nunder the Public Data License 1.0, as EDINET's terms ask (`null` for\nan SEC filing). Ratios are taken on the yen amounts, so no rate enters them.\nSuch a report tags no bitcoin count: the count is read from the\nsentence of its text that states the holding at the balance sheet\ndate, `financing.btc.count_basis` says so, and it is used only where\nit passes the same check as a tagged count. Filings made after the\nbalance sheet date are not listed for an EDINET filer.\n\nFor Strategy, two later statements from its own 8-Ks ride beside the\nfiling's figures, each with the 8-K's date and link: `atm_capacity`,\nthe amount each at the market program still has available for issuance\nand sale, and `btc_stated_since`, the bitcoin count the 8-K states.\nNeither is added into the figures above; the per BTC figures still\ndivide by the count in the periodic filing. Both are empty for every\nother company.\n\n`mnav` sits beside `financing`, under its own key, because it is not a\nfiling's figure. Its `basis` says which of two figures it is, and the\ntwo are never mixed.\n\nWith `basis: in house` it is derived for the newest session a share\nclose is stored for: market value (the shares outstanding the latest\n10-Q or 10-K states on its cover, times the stored close of the listed\nshare) over the value of the bitcoin held (the served holding times\nthe stored BTC price that session), and an enterprise value variant\nthat adds the filing's debt and preferred stock and takes off its\ncash. Every input is served with its own source and date, and they\ndiffer: the share count is the filing's and can be months older than\nthe close. Where the served holding is an estimate, the ratio uses it\nas displayed. An in house figure stands for 7 days after its session.\n\nWith `basis: CoinGecko` it is CoinGecko's own published figure\n(`m_nav`), for a company with no in house figure: a company with no\nSEC filing reading, a 20-F filer, no stored close, or share classes\nnot reviewed. It carries `source: CoinGecko`, the CoinGecko entity it\nwas read for, the day and time it was read, and `why_not_in_house`.\nThe share count and the method behind it are CoinGecko's, so it is not\ncomparable to the hundredth with an in house figure. It is read once a\nday and shown only while it is about a day old, and only at 0.25 or\nmore: under that `mnav` is `null` and `mnav_note` says so. Powered by\nCoinGecko.\n\nOn either basis the figure is shown only where the bitcoin is material\nto the company, which is where it is worth at least a tenth of the\nmarket value (10 or less). `mnav` is `null`, with `mnav_note` saying\nwhy, above that line and where neither basis has a figure (where\nCoinGecko publishes none for the company, or does not list it, the\nnote says so). Where no in house figure is derived, the note says what\nis missing as a fact: that PreReason holds no close of the listed share\nfrom the last 7 days, or that the company's filings state no bitcoin\nheld.\n","operationId":"getTreasuryHolding","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"20000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"One company's BTC treasury holding","intent":"charge","method":"evm"}]},"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9.-]{1,10}$"},"example":"MSTR"}],"responses":{"200":{"description":"The company's holding"},"400":{"description":"Malformed ticker"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Requires Pro or Enterprise tier"},"404":{"description":"Company is not on the tracked roster"}}}},"/api/metrics/{metric}":{"get":{"tags":["Metrics"],"summary":"Get single metric with interpretation","description":"Returns one metric with its analysis: trend (7d/30d/90d), momentum,\nconfidence score, percentile ranking, and data quality.\n\nA free key reads the metrics in the bitcoin category in full, and only\nthe latest reading of every other metric: its value in its unit, when\nit was taken, its source and its freshness (MetricLatestReading, with\naccess.served set to latest_reading). A basic key reads every metric in\nfull except the ones only pro briefings use, which GET /api/metrics names\nin pro_only_metrics: of those it reads the latest reading alone. The pro\ntier, and a paid call, read every metric in full.\n\nThe metric names this accepts are the ones GET /api/metrics returns,\nwhich needs no key and is always current.\n","operationId":"getMetric","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"10000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Get single metric with interpretation","intent":"charge","method":"evm"}]},"parameters":[{"name":"metric","in":"path","required":true,"description":"Metric identifier (hyphenated)","schema":{"type":"string","example":"bitcoin-price"}},{"$ref":"#/components/parameters/FormatParam"}],"responses":{"200":{"description":"Metric data with interpretation","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-PreReason-Tier":{"$ref":"#/components/headers/X-PreReason-Tier"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MetricData"},{"$ref":"#/components/schemas/MetricLatestReading"},{"$ref":"#/components/schemas/MetricLateRelease"}]}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/companies/{company}":{"get":{"tags":["Company Briefings"],"summary":"One listed company's briefing, whole, paid per call","description":"The whole briefing for one listed company in one call, as of today:\nits latest reported figures, what changed, its situations, and how it\nis valued and financed, each figure dated and sourced. It is the public\nform `GET /api/context?briefing=equities.company/{company}` serves a\nkey whose plan reaches the company's market. Sold for a company of a\nmarket that is live; one block alone is\n`GET /api/companies/{company}/{block}`.\n\nThe header's next results line, for a date the company announced in\nits own filing whose sentence also says when in the day, carries\n`detail.timing` (`before-open`, `after-close`, or null where the\nsentence states only a clock time) and\n`detail.release_time` (the release's clock time as the company wrote\nit, or null). Neither is the call's time; where the sentence says\nneither, both are left out.\n\nRefused before any price is quoted, so no payment is taken: a `date`\nor `time` (400: the figures carry their own filing dates and the\nratios keep no earlier version, so the briefing is sold as of today),\na malformed address (400), and an address that names no company sold\nhere (404 `NOT_FOUND`) or one whose statements have not been read\n(404 `NOT_COVERED_YET`). A key holder is never charged on this route:\nthe key's plan decides, as on `/api/context`.\n","operationId":"getCompanyBriefing","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.35"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"350000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"One listed company's briefing","intent":"charge","method":"evm"}]},"parameters":[{"name":"company","in":"path","required":true,"description":"The company. For a USA company, its ticker or CIK; for a Japanese company, its securities code; for a Korean company, its stock code; for an Indian company, its ISIN. Case does not matter.","schema":{"type":"string","pattern":"^[A-Za-z0-9.-]{1,33}$"},"example":"INE018A01030"},{"$ref":"#/components/parameters/FormatParam"}],"responses":{"200":{"description":"The company briefing, Markdown by default, JSON with format=json"},"400":{"description":"A date or time was sent, or the address is malformed"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"A key whose plan does not reach the company's market"},"404":{"description":"No company briefing is sold for this address, or none of its statements has been read"},"503":{"description":"The company could not be checked; no price was quoted and no payment taken"}}}},"/api/companies/{company}/{block}":{"get":{"tags":["Company Briefings"],"summary":"One block of a listed company's briefing, paid per call","description":"One block of the company's briefing, as of today, from its public form,\nwith the company's name, address, market and the time the briefing was\ncomputed. Nothing of the header block comes with another block: the\nheader is a block of its own. The whole briefing is\n`GET /api/companies/{company}`.\n\nA block name outside the list the `block` parameter takes is refused\nwith a 404 before any price is quoted. A block left out for this\ncompany answers 404 `BLOCK_NOT_COVERED_YET`, and nothing is charged.\n\nThe numbers block alone takes a `date` (YYYY-MM-DD): its figures as\nknown at the end of that day in the company's market, each with\n`knownBasis` (`filed`, `reported` or `deadline`) and `knownSince` (for\n`deadline`, the date our deadline rule assumes). A period the store\ncannot date is named and left out. Where the dated read is not\navailable the route answers 503 `DATED_READ_UNAVAILABLE`, and nothing\nis charged.\n\nRefused before any price is quoted, so no payment is taken: a `date`\non any other block, or a `time` (400: the figures carry their own\nfiling dates and the ratios keep no earlier version, so those blocks\nare sold as of today), a malformed address (400), and an address\nthat names no company sold\nhere (404 `NOT_FOUND`) or one whose statements have not been read\n(404 `NOT_COVERED_YET`). A key holder is never charged on this route:\nthe key's plan decides, as on `/api/context`.\n","operationId":"getCompanyBriefingBlock","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"50000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"One block of a listed company's briefing","intent":"charge","method":"evm"}]},"parameters":[{"name":"company","in":"path","required":true,"description":"The company. For a USA company, its ticker or CIK; for a Japanese company, its securities code; for a Korean company, its stock code; for an Indian company, its ISIN. Case does not matter.","schema":{"type":"string","pattern":"^[A-Za-z0-9.-]{1,33}$"},"example":"INE018A01030"},{"name":"block","in":"path","required":true,"description":"The block of the company briefing to return.","schema":{"type":"string","enum":["header","what_changed","situations","against_guidance","numbers","segments","valuation","capital_structure","quality","profitability","news"]},"example":"numbers"},{"name":"date","in":"query","required":false,"description":"The numbers block only. A past date (YYYY-MM-DD) whose figures to serve as known at the end of that day in the company's market. Refused on every other block. For a period's latest figures, including a later amendment's, leave date out.","schema":{"type":"string","format":"date"},"example":"2025-06-30"},{"$ref":"#/components/parameters/FormatParam"}],"responses":{"200":{"description":"The block, Markdown by default, JSON with format=json"},"400":{"description":"A date or time was sent, or the address is malformed"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"A key whose plan does not reach the company's market"},"404":{"description":"No such block, no company briefing sold for this address, none of its statements read, or the block is not covered for this company"},"503":{"description":"The company could not be checked; no price was quoted and no payment taken"}}}},"/api/events":{"get":{"tags":["Webhooks"],"summary":"What changed since your last read, paid per call or read with a key","description":"One page of PreReason's change events after a cursor: a live\nbriefing's state label changing, a tracked release becoming known\n(the Fed's weekly balance sheet, the FOMC statement and target range,\nTreasury auction results, the EIA's weekly crude oil and natural gas\nstocks, ECB and Bank of Japan policy rates), and, for the companies a\nread names, figures stored for a newer period, an event driven\nsituation the company briefing reports turning on, and filed news (for\nthe USA: an 8-K's material events, leadership changes and results).\nEach event says what\nchanged, when it happened, when PreReason knew it, the rule and where\nto fetch the briefing or metric it concerns; it carries no value.\n\nWith no cursor the read starts 24 hours back; each answer's\n`next_cursor` is where the next read starts. Events are kept 30 days.\nA company's events reach only a read that names the company in\n`companies`. `kinds` narrows company news; ownership reports come only\nto a read that names them.\n\nA key on the Basic or Pro plan reads its plan's events and is never\ncharged here. A caller with no key pays per read. A malformed cursor,\nan unknown event type, a malformed company, more than 200 companies\nor an unknown news kind answers 400, and nothing is charged.\n","operationId":"getChangeEvents","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"offers":[{"amount":"10000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"One page of change events","intent":"charge","method":"evm"}]},"parameters":[{"name":"cursor","in":"query","required":false,"description":"The next_cursor of your previous read. Left out, the read starts 24 hours back.","schema":{"type":"string","pattern":"^[0-9]{1,18}$"}},{"name":"types","in":"query","required":false,"description":"Event types, comma separated, from state.changed, release.published, company.figures_updated, company.situation_changed and company.news. Every type when left out.","schema":{"type":"string"},"example":"state.changed,release.published"},{"name":"companies","in":"query","required":false,"description":"Company addresses, comma separated, at most 200. A company's events reach only a read that names it.","schema":{"type":"string"},"example":"INE018A01030"},{"name":"kinds","in":"query","required":false,"description":"Company news kinds, comma separated, from earnings-release, material-event, leadership-change and ownership-report. Left out, every kind but ownership-report, which comes only when named.","schema":{"type":"string"},"example":"earnings-release,material-event"},{"name":"limit","in":"query","required":false,"description":"Events a page holds, 1 to 100. Default 50.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"A page of events, its next_cursor and whether more follow","content":{"application/json":{"schema":{"type":"object","required":["events","next_cursor","has_more"],"properties":{"events":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":"string"},"has_more":{"type":"boolean"},"note":{"type":"string","description":"Present only when the page holds no events, has_more is false and no companies were named: what to ask instead, with the count of market wide events from the last 30 days open to this read."}}}}}},"400":{"description":"A malformed cursor, an unknown event type, a malformed company, more than 200 companies, or an unknown news kind"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"A key on the free plan, which has no change events"}}}},"/api/news":{"get":{"tags":["Context"],"summary":"Dated records of what companies filed and what federal agencies and the Federal Reserve published","description":"Records PreReason stores, newest first, each with its source, its\ndate or time and a link: what companies filed (for the companies\nPreReason covers: 8-K items in the USA, EDINET in Japan, DART in Korea)\nand what federal agencies and the Federal Reserve published (the\nFederal Register's trade actions and export controls, Treasury buyback\noperations, the Federal Reserve's monetary policy releases). An answer\nholding a source's records carries that source's required notice in\n`notices`.\nName one company in `about` for its filings alone. Every answer names\nthe sources it read; it states records, not reasons.\n\nA filed 8-K line names the filing's substantive items in PreReason's\nfixed order of significance, at most three, with a count of the rest;\nitem 7.01 (Regulation FD disclosure) and item 9.01 (financial\nstatements and exhibits) are carriers, named only when a filing\ncarries nothing else.\n\nEach record is in the window by the date it shows. A source that\ndates by day prints that day with no clock time: EDGAR's own filing\ndate, DART's receipt date, the Federal Register's publication date and\nTreasury's buyback operation date. EDINET's submission and the Fed's\nrelease print their own clock.\n\nThe order: by the date each record shows, newest first; within one\ndate, the records that show a time first, newest first, then the\nrecords dated by day alone; ties go by id.\n\nNeeds an API key on any plan, and each read counts as one call. A bad\ndate, kind or limit answers 400; a company PreReason does not cover\nanswers 404.\n","operationId":"getNews","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"about","in":"query","required":false,"description":"One company, by ticker or ISIN. Left out, records of every company and agency read.","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"filed (company filings) or official (federal agency and Federal Reserve documents). Both when left out.","schema":{"type":"string","enum":["filed","official"]}},{"name":"since","in":"query","required":false,"description":"The first date of the window, YYYY-MM-DD. Seven days before until when left out.","schema":{"type":"string","format":"date"}},{"name":"until","in":"query","required":false,"description":"The last date of the window, YYYY-MM-DD. Today (UTC) when left out.","schema":{"type":"string","format":"date"}},{"name":"as_of","in":"query","required":false,"description":"Only records dated on or before this date, YYYY-MM-DD; in place of until.","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"Records one read returns, 1 to 25. Default 10.","schema":{"type":"integer","minimum":1,"maximum":25}}],"responses":{"200":{"description":"The records, the window and the sentence naming the sources read","content":{"application/json":{"schema":{"type":"object","required":["about","window","records","coverage"],"properties":{"about":{"type":"object","nullable":true},"window":{"type":"object"},"records":{"type":"array","items":{"type":"object"}},"coverage":{"type":"string"},"notices":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"not_read":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"A bad date, kind or limit, a window over 92 days, or kind official with about"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"A company PreReason does not cover, or one whose filings this version does not read"},"503":{"description":"No source could be read"}}}},"/api/context":{"get":{"tags":["Context"],"summary":"Get context briefing","description":"The primary endpoint for consuming PreReason data. Returns a pre-computed context bundle\nfor the requested briefing, including metrics, trend analysis and confidence scores.\n\nBriefings are tier-gated. GET /api/briefings lists every briefing with\nthe tier it needs, and needs no key itself.\n\nCompany briefings (live for the USA on Basic and above, and for Japan,\nKorea and India on Pro and above) are requested as\n`equities.company/<company>`: a USA ticker or CIK (`equities.company/NVDA`),\na Japanese securities code (`equities.company/7203`), a Korean stock code\n(`equities.company/005930`) or an Indian company's ISIN\n(`equities.company/INE018A01030`). For a USA company a\nbriefing gives its latest figures as filed, each dated by its filing,\nwhat changed, its situations, and how it is valued and financed; for a\nJapanese company the same, from its annual securities report or, where it\nhas filed one since, its half year report, as filed on EDINET; for a\nKorean company the same, from its annual business report or, where it\nhas filed one since, its half year or quarterly report, as filed on DART.\nFor an Indian company it gives the latest quarter's results statement, a\nshare price, and a market capitalisation where a current share count is\nread.\nThat id carries a company, so it is not among the fixed ids listed\nunder the `briefing` parameter. In JSON a company briefing carries\n`notCoveredYet`: the blocks and figures that cannot be seen for\nthat company, left out of the briefing and named there once (the\nfield's name is historical and promises nothing).\n","operationId":"getContext","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"briefing","in":"query","required":true,"description":"Briefing ID (dot-namespaced, e.g., btc.context). A company briefing\nis `equities.company/<company>` (a USA ticker or CIK, a Japanese\nsecurities code, a Korean stock code, or an Indian company's ISIN) and\nis accepted beside the ids listed.\n","schema":{"type":"string","enum":["btc.quick-check","btc.context","btc.pulse","btc.grid-stress","macro.snapshot","cross.correlations","btc.momentum","btc.on-chain","btc.miner-survival","macro.liquidity","cross.breadth","btc.etf-flows","btc.full","btc.factors","btc.energy","btc.treasury","cross.regime","fx.liquidity","macro.rates","cross.ai-compute","commodities.energy-basket","macro.auctions","bonds.context","bonds.full","eth.context"],"example":"btc.context"}},{"name":"format","in":"query","description":"Response format. Default is markdown (LLM-optimized).","schema":{"type":"string","enum":["json","markdown"],"default":"markdown"},"example":"json"},{"name":"date","in":"query","description":"Historical date (YYYY-MM-DD). Returns context as it would have appeared on that date:\neach metric is its newest period released by the end of that day (UTC), at the value public then\nwhere PreReason holds it as first published, and marked where it may be a later revision. It carries\n`period` (what it describes), `known_since` (when it was public, at the latest) and\n`known_basis` (released, fetched, release_schedule or unknown): `released` is the publisher's\nstated time; `fetched` is PreReason's first read of the row; `release_schedule` is the row's\nstamp plus its series' release lag (for a Treasury auction, the close plus one day), PreReason's\nrule for when it was public at the latest, used where PreReason first held the row later than\nthat; `unknown` means no time is stated (`known_since` is null, a revised series with no release\ntime and no read inside its schedule). The historical context\nblocks and btc.treasury's company holdings are dated the same way.\nFor a period's latest figures, including later corrections, leave date out.\nTier-gated: Free 30d rolling; Basic 3 years back, Bitcoin briefings from Jan 2025; Pro all data.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-02-01"}}],"responses":{"200":{"description":"Context data for the requested briefing","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-PreReason-Tier":{"$ref":"#/components/headers/X-PreReason-Tier"}},"content":{"application/json":{"schema":{"type":"object","description":"Structure varies by briefing. All include generated_at timestamp."}},"text/markdown":{"schema":{"type":"string","description":"LLM-optimized markdown with sections, figures, and context."}}}},"400":{"description":"Missing or invalid briefing parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Missing required parameter: briefing"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Briefing not available on your tier, or date outside tier access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["BRIEFING_RESTRICTED","DATE_RESTRICTED"],"example":"BRIEFING_RESTRICTED"},"message":{"type":"string","example":"Briefing 'btc.full' requires Pro tier"},"details":{"type":"object","properties":{"briefing":{"type":"string","example":"btc.full"},"required_tier":{"type":"string","example":"pro"},"your_tier":{"type":"string","example":"free"}}},"upgrade_url":{"type":"string","example":"/pricing?tier=pro"}}}}}},"404":{"description":"Briefing does not exist. For a company briefing, a listed company\nwhose results statements have not been read answers `NOT_COVERED_YET` with\nthis status: a flat body of `error` (`NOT_COVERED_YET`), `message`\nand `market`. No plan changes that answer.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Briefing 'quick-check' does not exist"},"details":{"type":"object","properties":{"briefing":{"type":"string","example":"quick-check"},"available_briefings":{"type":"array","items":{"type":"string"},"example":["btc.quick-check","btc.context","macro.snapshot"]}}}}}}}}}},"410":{"description":"Briefing has been deprecated and merged into another","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"BRIEFING_DEPRECATED"},"message":{"type":"string","example":"Briefing 'percentile-context' has been merged into 'btc.momentum'. Use briefing=btc.momentum instead."},"replacement":{"type":"string","example":"btc.momentum"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/briefings":{"get":{"tags":["Context"],"summary":"List available briefings (RESTful alias)","description":"Same catalog as `GET /api/context/briefings`, at the path most callers\nguess first. Each entry carries an `href` so the id you read is the\naddress you can fetch.\n","operationId":"listBriefingsAlias","security":[],"responses":{"200":{"description":"List of briefings available to your tier"}}}},"/api/briefings/{id}":{"get":{"tags":["Context"],"summary":"Get one briefing by id","description":"Alias for `GET /api/context?briefing={id}`. Accepts the dotted ids the\ncatalog returns, e.g. `/api/briefings/macro.snapshot`. A `.md` or\n`.json` suffix sets the format.\n\nRequires an API key. Unlike the short URL aliases, this route is not\nx402-payable — free tier is free of charge, not keyless, so sign up for\na key rather than paying per call.\n","operationId":"getBriefingById","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Briefing ID as returned by the catalog (dot-namespaced).","schema":{"type":"string","example":"macro.snapshot"}},{"$ref":"#/components/parameters/FormatParam"},{"$ref":"#/components/parameters/DateParam"}],"responses":{"200":{"description":"Briefing context"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown briefing id; body lists the ids you can access"}}}},"/api/context/briefings":{"get":{"tags":["Context"],"summary":"List available briefings","description":"Returns all briefings available for your tier, with descriptions and metadata.\nUseful for agents to discover what context is available before requesting it.\n","operationId":"listBriefings","security":[],"responses":{"200":{"description":"List of briefings available to your tier","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","example":"free"},"briefings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"btc.context"},"name":{"type":"string","example":"Bitcoin Market Context"},"description":{"type":"string","example":"Full Bitcoin market context with on-chain and macro indicators"},"tier":{"type":"string","enum":["free","basic","pro"],"example":"free"},"derivatives":{"type":"boolean","enum":[true],"description":"Present, as true, on a briefing that serves any series that measures a futures, swap or options market (see `instrument` on a metric); absent otherwise."},"accessible":{"type":"boolean","example":true}}}},"total":{"type":"integer","example":17},"accessible":{"type":"integer","example":6}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/metrics":{"get":{"tags":["Metrics"],"summary":"List all metrics","description":"Returns every available metric with its name, description and category.\nUse this to discover what individual metrics are available.\n","operationId":"listMetrics","security":[],"parameters":[{"name":"category","in":"query","description":"Filter by category","schema":{"type":"string","enum":["bitcoin","calculated","eth","macro"]},"example":"bitcoin"},{"name":"search","in":"query","description":"Search by name or description","schema":{"type":"string"},"example":"hash"}],"responses":{"200":{"description":"List of available metrics","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-PreReason-Tier":{"$ref":"#/components/headers/X-PreReason-Tier"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/metrics/bitcoin-price/history":{"get":{"tags":["Metrics"],"summary":"Bitcoin price history","description":"Daily BTC price time series, one point a day: the day's last price. Each point names\nthe source its close came from (`data[].source`): Blockchain.com to 2025-08-31 and\nCoinGecko after it, except Kraken for 2026-08-28 and Coinbase for 2026-08-29 to 08-31\nand 2026-09-14 to 09-29. Since 2026-10-01 each day's close is asked from CoinGecko; a\nday it does not answer is Coinbase's and says so, and the current day's point is the\nlatest price so far, most often Coinbase's. `sources` lists each source served\nwith its first and last date, and `attribution` carries \"Powered by CoinGecko.\"\nwhenever a CoinGecko close is served. Date ranges by tier:\n- **Free**: Rolling 30-day window\n- **Basic**: From January 1, 2025\n- **Pro/Enterprise**: All available data (from August 18, 2010)\n","operationId":"getBtcPriceHistory","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","description":"Start date (YYYY-MM-DD). Defaults to 30 days ago.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"}},{"name":"to","in":"query","description":"End date (YYYY-MM-DD), the whole day, so its point is that day's last price like every other day's. Defaults to now.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-02-21"}},{"name":"limit","in":"query","description":"Maximum data points (1-1000, default 100)","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"Bitcoin price history","content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string","example":"bitcoin-price"},"from":{"type":"string","example":"2026-01-01"},"to":{"type":"string","example":"2026-02-21"},"count":{"type":"integer","example":52},"source":{"type":"string","description":"Every source the points name, newest first, joined by commas.","example":"CoinGecko"},"sources":{"type":"array","description":"Each source served once, in the order the points first name it.","items":{"type":"object","properties":{"name":{"type":"string","example":"CoinGecko"},"points":{"type":"integer","example":52},"first_date":{"type":"string","example":"2026-01-01"},"last_date":{"type":"string","example":"2026-02-21"},"notice":{"type":"string","description":"The notice this source's terms record requires, when it requires one.","example":"Powered by CoinGecko."}}}},"attribution":{"type":"string","description":"Names every source served, with each notice their terms records require.","example":"Sources: CoinGecko. Powered by CoinGecko."},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-15"},"price":{"type":"number","example":97500},"source":{"type":"string","description":"The source this close came from.","example":"CoinGecko"},"interpolated_from":{"type":"string","description":"On a filler close only, the day whose close it repeats.","example":"2024-01-15"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Date range outside tier access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"DATE_RESTRICTED"},"message":{"type":"string","example":"Date '2024-01-01' is outside your tier's access range"},"upgrade_url":{"type":"string","example":"/pricing?reason=historical-access"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/health":{"get":{"tags":["System"],"summary":"Health check","description":"Returns API health status. No authentication required.","operationId":"getHealth","security":[],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string","example":"1.0.0"},"endpoints":{"type":"object"}}}}}}}}},"/api/health/ready":{"get":{"tags":["System"],"summary":"Readiness (database)","description":"Whether the database answered a read just now. 200 when it did, 503 when it\ndid not or took longer than three seconds, so an uptime monitor can read the\nanswer from the status code alone. A result is reused for up to ten seconds,\nand checked_at says when it was taken. No authentication required.\n","operationId":"getHealthReady","security":[],"responses":{"200":{"description":"The database answered","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"database":{"type":"string","enum":["ok"]},"latency_ms":{"type":"integer","example":38},"checked_at":{"type":"string","format":"date-time"}}}}}},"503":{"description":"The database did not answer in time, or this instance is not reading it","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["down"]},"database":{"type":"string","enum":["error","timeout","demo_mode"]},"checked_at":{"type":"string","format":"date-time"}}}}}}}}},"/api/status":{"get":{"tags":["System"],"summary":"System status","description":"Public system status page data. Returns operational status for API, database,\nand data pipeline components. No authentication required.\n","operationId":"getStatus","security":[],"responses":{"200":{"description":"System status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["operational","degraded","outage"],"example":"operational"},"components":{"type":"object"},"lastChecked":{"type":"string","format":"date-time"}}}}}}}}},"/api/version":{"get":{"tags":["System"],"summary":"API version","description":"Returns current API version and supported versions. No authentication required.","operationId":"getVersionConfig","security":[],"responses":{"200":{"description":"Version configuration","content":{"application/json":{"schema":{"type":"object","properties":{"currentVersion":{"type":"string","example":"v1"},"supportedVersions":{"type":"array","items":{"type":"string"},"example":["v1"]}}}}}}}}},"/api/headline":{"get":{"tags":["System"],"summary":"Headline metrics","description":"Returns a small set of key market metrics for display (e.g., login page, dashboards).\nCached 5 minutes. No authentication required.\n","operationId":"getHeadline","security":[],"responses":{"200":{"description":"Headline metrics","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/openapi/spec.json":{"get":{"tags":["System"],"summary":"OpenAPI specification (JSON)","description":"Returns this OpenAPI specification in JSON format.","operationId":"getOpenApiJson","security":[],"responses":{"200":{"description":"OpenAPI 3.0 specification","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/openapi/spec.yaml":{"get":{"tags":["System"],"summary":"OpenAPI specification (YAML)","description":"Returns this OpenAPI specification in YAML format.","operationId":"getOpenApiYaml","security":[],"responses":{"200":{"description":"OpenAPI 3.0 specification","content":{"text/yaml":{"schema":{"type":"string"}}}}}}},"/api/openapi/ui":{"get":{"tags":["System"],"summary":"Interactive API reference","description":"Browsable API reference rendered from this specification, with\ntry-it-out. Unauthenticated, like the specification itself.\n","operationId":"getOpenApiUi","security":[],"responses":{"200":{"description":"HTML documentation page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/openapi/status":{"get":{"tags":["System"],"summary":"Specification metadata","description":"Version, endpoint count and last-modified time for this specification.\nUse it to detect that the contract changed without downloading it.\n","operationId":"getOpenApiStatus","security":[],"responses":{"200":{"description":"Specification metadata"}}}},"/api/mcp":{"post":{"tags":["System"],"summary":"MCP server (Model Context Protocol)","description":"Stateless Streamable HTTP transport for MCP-compatible AI agents.\nThe tools are get_context, get_metric, list_briefings, list_metrics and\nget_health, every one read only. Call tools/list for the set this server\nis serving now.\n\nNo key is needed to connect, which is why this operation declares no\nsecurity requirement. list_briefings, list_metrics and get_health answer\nan anonymous caller. get_context and get_metric need a key, sent as the\nheader below. No MCP answer hands out a key or asks for one; see the\nAgent access tag for how an agent gets one.\n\nConfigure in your MCP client:\n```json\n{\n  \"mcpServers\": {\n    \"prereason\": {\n      \"url\": \"https://api.prereason.com/api/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer YOUR_API_KEY\" }\n    }\n  }\n}\n```\n","operationId":"mcpEndpoint","security":[],"responses":{"200":{"description":"MCP response"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/agent/claims":{"post":{"tags":["Agent access"],"summary":"Start a key claim from inside an agent's session","description":"Creates a claim and returns two things: a claim_code the human can read\n(PR-XXXX-XXXX) and a one time claim_token only the agent holds. Show the\nhuman approve_url; they sign in (or create the account there) and click\nApprove. Then poll GET /api/agent/claims/{code} with the claim_token as\na Bearer until status is approved; that response carries the api_key\nonce. The key is attached to the approving human's account and named\n\"Agent: <client_name>\".\n\nLimits: 5 claims an hour per address, 20 pending per address, 2,000\npending globally (503 with Retry-After). A claim lives 15 minutes; the\napproval page can extend it to at most 60 minutes from creation.\n","operationId":"createAgentClaim","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","maxLength":64,"description":"The app or agent asking. Printable text, no URLs. Becomes the key name.","example":"Claude Desktop"},"purpose":{"type":"string","maxLength":200,"description":"One line on what the key is for, shown on the approval page."},"client_version":{"type":"string","maxLength":32}}}}}},"responses":{"201":{"description":"Claim created; the token is shown once","content":{"application/json":{"schema":{"type":"object","properties":{"claim_code":{"type":"string","example":"PR-7K3F-9Q2M"},"claim_token":{"type":"string","description":"Bearer for the poll. Shown once, never stored in plaintext.","example":"prc_..."},"status":{"type":"string","example":"pending"},"approve_url":{"type":"string","example":"https://www.prereason.com/claim/PR-7K3F-9Q2M"},"expires_at":{"type":"string","format":"date-time"},"expires_in":{"type":"integer","example":900},"poll":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","example":"GET"},"header":{"type":"string","example":"Authorization: Bearer <claim_token>"},"interval_seconds":{"type":"integer","example":5}}},"instructions":{"type":"string"},"docs":{"type":"string"}}}}}},"400":{"description":"VALIDATION_ERROR with the offending field"},"429":{"description":"RATE_LIMITED, with Retry-After"},"503":{"description":"CLAIM_CAPACITY, with Retry-After"}}}},"/api/agent/claims/{code}":{"get":{"tags":["Agent access"],"summary":"Poll a claim; delivers the key once after approval","description":"Authorization: Bearer <claim_token>. Answers status pending (keep\npolling every poll_interval seconds), approved with the api_key on the\nfirst poll after approval, delivered on every later poll (no key in the\nbody), denied, or expired. An unknown code and a wrong token are the\nsame 404. 30 polls a minute per address.\n","operationId":"pollAgentClaim","security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","pattern":"^PR-[ABCDEFGHJKMNPQRSTUVWXYZ23456789]{4}-[ABCDEFGHJKMNPQRSTUVWXYZ23456789]{4}$"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer prc_..."}}],"responses":{"200":{"description":"The claim's status; on the first poll after approval, the key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","delivered","denied","expired"]},"claim_code":{"type":"string"},"api_key":{"type":"string","description":"Present once, on the first poll after approval"},"delivered_once":{"type":"boolean"},"key":{"type":"object"},"account":{"type":"object"},"how_to_use":{"type":"object"},"approve_url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"poll_interval":{"type":"integer"},"error":{"type":"string","description":"KEY_ISSUE_FAILED when minting failed; poll again after retry_after seconds"},"retry_after":{"type":"integer"},"message":{"type":"string"},"next":{"type":"string"},"docs":{"type":"string"}}}}}},"404":{"description":"CLAIM_NOT_FOUND (unknown code or wrong token, indistinguishable)"},"429":{"description":"RATE_LIMITED, with Retry-After"}}}}},"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key as Bearer token. Get your key at [prereason.com/signup](https://www.prereason.com/signup).\n\n```\nAuthorization: Bearer pr_live_xxx\n```\n"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"The same API key in its own header, for clients that cannot set `Authorization`.\n\n```\nX-API-Key: pr_live_xxx\n```\n"}},"parameters":{"FormatParam":{"name":"format","in":"query","description":"Response format (json or markdown). Default is markdown.","schema":{"type":"string","enum":["json","markdown"],"default":"markdown"}},"DateParam":{"name":"date","in":"query","description":"A past date, YYYY-MM-DD: the briefing as of the end of that day (UTC; a company's numbers at the end of the day in its own market), for the periods released by then. Each figure says when it was public, or that it may be a later revision PreReason holds in its place. For a period's latest figures, including later corrections, leave date out. Tier-gated access.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}},"schemas":{"MetricData":{"type":"object","properties":{"metric":{"type":"string","description":"The series' public name, the name GET /api/metrics lists; a short name such as dxy answers as etf-uup. Since 2026-10-10; it carried the stored identifier before, which is now in `stored_name`.","example":"bitcoin-price"},"name":{"type":"string","description":"Equal to `metric`: the series' public name, under which the answer is worded.","example":"bitcoin-price"},"stored_name":{"type":"string","description":"The identifier PreReason stores the series under. It names no source; the series' source is in `source`.","example":"btc_price_usd"},"instrument":{"type":"string","enum":["futures","swap","options"],"description":"Present on a series that measures a futures, swap or options market (`futures`, `swap` or `options`), including a series PreReason calculates from one, and absent for every other series."},"display_name":{"type":"string","example":"Bitcoin Price"},"timestamp":{"type":"string","format":"date-time"},"period":{"type":"object","description":"Present only for a series dated by its month or quarter (since 2026-10-10): the month or quarter the figure describes, its basis where the source states one, and its release where the row carries one. `timestamp` is unchanged, and `data_quality.age_display` counts from `released`, or names the period when no release is stored.","properties":{"period":{"type":"string","description":"The month or quarter the figure describes (\"2026-09\", or \"2026-Q1\" for a quarter).","example":"2026-09"},"period_words":{"type":"string","description":"The same period in words.","example":"September 2026"},"basis":{"type":"string","nullable":true,"description":"\"monthly average\" where the source states its figure is the month's average; null otherwise.","example":"monthly average"},"released":{"type":"string","format":"date","nullable":true,"description":"The row's own release day, or null when the row carries none.","example":"2026-10-02"},"released_as":{"type":"string","nullable":true,"description":"What `released` is: \"release\" for the publisher's release, or \"file's date\" for the date of the publisher's file (the World Bank's monthly prices). Null when `released` is null.","example":"file's date"},"description":{"type":"string","description":"The period, its basis and its release in one line.","example":"September 2026, the monthly average (World Bank, in its file of 2026-10-02)"}}},"interpretation":{"$ref":"#/components/schemas/Interpretation"},"trend":{"$ref":"#/components/schemas/Trend"},"stored_range":{"type":"object","description":"Where the reading sits in its stored daily history, as a briefing with percentiles serves it, with the facts the statement is made from. The Markdown prints the statement as a \"Range:\" line under the rank. Absent when nothing is said: under two years of stored history, a \"since\" date less than a year back, a series that grows by construction, or a nominal stock of money or debt (M2, EU M3, US total debt, BIS global liquidity). Absent too for a series dated by its month or quarter with fewer than 24 monthly or 8 quarterly stored readings, where no percentile is served, and for dealer-takedown-pct and indirect-bidder-pct, which are not ranked. For SPY, QQQ, IWM, UUP and VXX, whose older history is held as month closes (VXX: week closes), a stored day that is such a close is named by its period: its `date`, `highest_since`, `lowest_since` or `history_from` is the month (\"2024-01\") or the week's first day, `stored_high` and `stored_low` carry `basis`, and a dated read counts no such close before its period ends.","properties":{"statement":{"type":"string","example":"Highest since 2002-05-14, when it read 5.32%. The stored high is 15.84% on 1981-09-30, 10.53 pp above this reading."},"highest_since":{"type":"string","description":"The day the reading is the highest since, or stored_history when no stored day is at or above it. Absent when not said.","example":"2002-05-14"},"lowest_since":{"type":"string","description":"The day the reading is the lowest since, or stored_history when no stored day is at or below it. Absent when not said."},"stored_high":{"type":"object","properties":{"value_formatted":{"type":"string","example":"15.84%"},"date":{"type":"string","example":"1981-09-30"},"basis":{"type":"string","enum":["month's last close","week's last close"],"description":"Present only where the stored high is a month's or a week's last close; `date` is then that month or week."}}},"stored_low":{"type":"object","properties":{"value_formatted":{"type":"string","example":"0.52%"},"date":{"type":"string","example":"2020-08-04"},"basis":{"type":"string","enum":["month's last close","week's last close"],"description":"Present only where the stored low is a month's or a week's last close; `date` is then that month or week."}}},"history_from":{"type":"string","description":"The first stored day the statement reads from.","example":"1962-01-02"}}},"context":{"type":"string","description":"Human-readable context summary"},"source":{"type":"string","example":"CoinGecko"},"display":{"type":"string","enum":["yes","notice","no"],"description":"Whether a Business plan's display licence covers showing this figure to your users. yes; notice, when shown with its provider's credit (named on the Data sources page); or no, when the provider's terms do not allow it, were not read, or the value is calculated from inputs whose sources' terms have not been traced."},"notices":{"type":"array","items":{"type":"string"},"description":"The notices the row's sources require shown with the figure, each in its terms record's own words (\"Powered by CoinGecko.\"), and Korea Customs' naming its release's title and date. Absent when no source requires one; the New York Fed's reference rates carry theirs as their source.","example":["Powered by CoinGecko."]},"data_quality":{"$ref":"#/components/schemas/DataQuality"}}},"MetricLatestReading":{"type":"object","properties":{"metric":{"type":"string","description":"The series' public name, as MetricData carries it.","example":"treasury-10y"},"name":{"type":"string","description":"Equal to `metric`, as MetricData carries it.","example":"treasury-10y"},"stored_name":{"type":"string","description":"The identifier PreReason stores the series under. It names no source; the series' source is in `source`.","example":"fred_treasury_10y"},"instrument":{"type":"string","enum":["futures","swap","options"],"description":"Present on a series that measures a futures, swap or options market (`futures`, `swap` or `options`), including a series PreReason calculates from one, and absent for every other series."},"display_name":{"type":"string","example":"10-Year Treasury"},"timestamp":{"type":"string","format":"date-time"},"reading":{"type":"string","description":"The value in its unit, as the full answer's sentence prints it","example":"5.26%"},"source":{"type":"string"},"display":{"type":"string","enum":["yes","notice","no"],"description":"Whether a Business plan's display licence covers showing this figure to your users. yes; notice, when shown with its provider's credit (named on the Data sources page); or no, when the provider's terms do not allow it, were not read, or the value is calculated from inputs whose sources' terms have not been traced."},"notices":{"type":"array","items":{"type":"string"},"description":"The notices the row's sources require shown with the figure, each in its terms record's own words (\"Powered by CoinGecko.\"), and Korea Customs' naming its release's title and date. Absent when no source requires one; the New York Fed's reference rates carry theirs as their source.","example":["Powered by CoinGecko."]},"data_quality":{"$ref":"#/components/schemas/DataQuality"},"access":{"type":"object","properties":{"served":{"type":"string","enum":["latest_reading"]},"withheld":{"type":"array","items":{"type":"string"},"description":"The fields of MetricData this answer leaves out","example":["interpretation","trend","context"]},"full_answer_tier":{"type":"string","enum":["basic","pro"],"description":"The lowest tier that reads this metric in full, pro for a metric only pro briefings use"},"note":{"type":"string"},"upgrade_request":{"type":"object","description":"How an agent asks the key's owner for the tier full_answer_tier names, as a tier refusal offers it"}}}}},"MetricLateRelease":{"type":"object","description":"The newest stored reading of a series whose release is late (past its usual day plus a grace): the reading, its date and its source, with the late release named. No signal, confidence, trend or context is served until the release is stored.","properties":{"metric":{"type":"string","description":"The series' public name, as MetricData carries it.","example":"korea-exports-20d"},"name":{"type":"string","description":"Equal to `metric`, as MetricData carries it.","example":"korea-exports-20d"},"stored_name":{"type":"string","description":"The identifier PreReason stores the series under. It names no source; the series' source is in `source`."},"display_name":{"type":"string"},"timestamp":{"type":"string","format":"date-time","description":"The stored reading's own date."},"reading":{"type":"string","description":"The value in its unit, as the full answer's sentence prints it."},"release_clause":{"type":"string","description":"The source's own statement of the reading, when it has one (Korea Customs' clause)."},"source":{"type":"string"},"display":{"type":"string","enum":["yes","notice","no"],"description":"Whether a Business plan's display licence covers showing this figure to your users, as MetricLatestReading's display."},"data_quality":{"$ref":"#/components/schemas/DataQuality"},"release_late":{"type":"object","description":"The late release.","properties":{"stored_window":{"type":"string","description":"The newest window stored (YYYY-MM)."},"late_window":{"type":"string","description":"The first window after it whose release is overdue (YYYY-MM)."},"late_count":{"type":"integer","description":"How many windows after the stored one are overdue."},"expected_about":{"type":"string","format":"date","description":"The day the late window's release usually comes."},"late_since":{"type":"string","format":"date-time","description":"The instant from which it counts as late (that day plus the grace, 00:00 UTC)."},"text":{"type":"string","description":"One sentence naming the late release, the same on every surface that serves the series."}}},"withheld":{"type":"array","items":{"type":"string"},"description":"The fields of MetricData this answer leaves out, by name.","example":["interpretation","trend","context"]},"note":{"type":"string","description":"Why the interpretation, trend and context are withheld."}}},"Interpretation":{"type":"object","description":"The reading's signal and its confidence. For dealer-takedown-pct and indirect-bidder-pct, whose readings are each the latest note or bond auction of any term, only `not_measured` is served: no signal, confidence, confidence_label or factors.","properties":{"not_measured":{"type":"string","description":"Why no signal is read, in place of signal, confidence, confidence_label and factors. Served for dealer-takedown-pct and indirect-bidder-pct only; absent everywhere else.","example":"each reading is the latest auction of any term, so a rank or a trend signal would compare different securities"},"signal":{"type":"string","enum":["bullish","bearish","neutral","above-trend","below-trend","at-trend"],"example":"bullish","description":"The reading's word, the same one briefings serve for the metric. Crypto series read bullish, bearish or neutral. Every other metric reads above-trend, below-trend or at-trend: where its value sits against its trend, so a Treasury yield at the top of its range reads above-trend."},"confidence":{"type":"number","minimum":15,"maximum":90,"example":75,"description":"Signal clarity: how clearly the current reading supports its own label, scored from 15 to 90 on four facts about the reading (how far past the boundary that decided the label it sits, whether its 7 day and 30 day moves point the way the label expects, how extreme it is in its history, and whether it is current against its own publication schedule, the same judgement data_quality.stale states). It is not a probability that the label is right, says nothing about what any price does next, and has not been calibrated against outcomes."},"confidence_label":{"type":"string","enum":["Very High","High","Medium","Low","Very Low"],"example":"High"},"factors":{"type":"object","description":"The four factors behind confidence, each 0 to 100.","properties":{"signal_strength":{"type":"number"},"trend_consistency":{"type":"number"},"percentile_score":{"type":"number"},"data_quality":{"type":"number","description":"100 while the reading is current on its own publication schedule (data_quality.stale is false), 60 once stale, 30 once critical."}}}}},"Trend":{"type":"object","properties":{"direction":{"type":"string","enum":["rising","falling","flat"],"description":"Absent where no change window was measured (every 7, 30 and 90 day flag false): the two any-term auction shares, or a series with no recent reading. It holds the label the last live answer served in the past 6 hours: a new direction needs the 7 day change more than a quarter past the series' flat band, and a held one stays until the change falls back inside three quarters of it. A historical date has no memory.","example":"rising"},"change_7d":{"type":"number","example":2.5},"change_7d_available":{"type":"boolean","description":"True when change_7d was measured against a reading close to 7 days before this one. False when no reading sat close enough: change_7d is then the change against the nearest earlier reading, or 0 when there is none, and is not a 7 day change. Always false, with every window and a change of 0, for a series that mixes auction terms (dealer-takedown-pct, indirect-bidder-pct): each reading is the latest note or bond auction of any term, so a window would compare two different securities.","example":true},"change_30d":{"type":"number","example":5.1},"change_30d_available":{"type":"boolean","description":"True when change_30d was measured against a reading close to 30 days before this one. False when no reading sat close enough: change_30d is then the change against the nearest earlier reading, or 0 when there is none, and is not a 30 day change.","example":true},"change_90d":{"type":"number","example":12.3},"change_90d_available":{"type":"boolean","description":"True when change_90d was measured against a reading close to 90 days before this one. False when no reading sat close enough: change_90d is then the change against the nearest earlier reading, or 0 when there is none, and is not a 90 day change.","example":true},"change_unit":{"type":"string","enum":["percent","absolute"],"description":"The unit of change_7d, change_30d and change_90d. percent is a relative change. absolute is a difference in the metric's own unit: percentage points for a rate, standard deviations for a score, contracts for a position, or its currency. A series that can take either sign by what it is (a spread, a distance, a z score, a flag, a rank, a net position or flow) always measures its changes as absolute differences, and so does a level at or below zero.","example":"percent"},"momentum":{"type":"string","enum":["accelerating","decelerating","steady"],"example":"steady"},"momentum_description":{"type":"string","example":"Steady upward momentum"},"percentile":{"type":"number","minimum":0,"maximum":100,"description":"Where the reading ranks, the same in a briefing and on this route: among every daily close stored for the metric, or, for a series that grows by construction such as hash rate or difficulty, its change over 7 days among the weekly changes in its history. Null, with no percentile_label, for dealer-takedown-pct and indirect-bidder-pct: each reading is the latest note or bond auction of any term, so a rank would compare different securities.","example":85},"percentile_label":{"type":"string","description":"The percentile's band word, or \"not measured\" where no rank was measured. Absent for a series that holds one value in all its stored readings, for a series dated by its month or quarter with fewer than 24 monthly or 8 quarterly stored readings, and for dealer-takedown-pct and indirect-bidder-pct.","example":"high"},"percentile_history_days":{"type":"integer","description":"The days of history the percentile was ranked in, from the first stored close to the reading (or the history read for a weekly change rank). Absent when that span is not known, where no rank was measured, for a series that holds one value in all its stored readings, for a series dated by its month or quarter with fewer than 24 monthly or 8 quarterly stored readings, and for dealer-takedown-pct and indirect-bidder-pct.","example":23641},"same_value":{"type":"object","description":"Present only for a series that holds the same value in all its stored readings: no percentile is served (percentile is null, with no percentile_label), and this says how many readings and since which day. Absent for every other series.","properties":{"readings":{"type":"integer","example":105},"since":{"type":"string","format":"date","example":"2026-05-08"}}},"percentile_readings":{"type":"integer","description":"How many stored readings the served percentile was taken among. Present only for a series dated by its month or quarter, and only when a percentile is served.","example":440},"percentile_since":{"type":"string","description":"The month or quarter of the first of those readings (\"1990-01\", or \"2000-Q1\" for a quarter). Present under the same conditions as percentile_readings.","example":"1990-01"},"change_30d_from":{"type":"string","description":"The month the 30 day change was measured from (\"2026-07\"). Present only for a series dated by its month, and only where that change is measured. Absent for a quarterly series: no 30 day change is measured between two of its readings.","example":"2026-07"},"change_90d_from":{"type":"string","description":"The month or quarter the 90 day change was measured from (\"2026-05\"). Present only for a series dated by its month or quarter, and only where that change is measured.","example":"2026-05"}}},"DataQuality":{"type":"object","properties":{"age_hours":{"type":"number","example":2.5},"stale":{"type":"boolean","example":false},"status":{"type":"string","enum":["fresh","warning","stale"],"example":"fresh"}}},"MetricListItem":{"type":"object","properties":{"name":{"type":"string","example":"bitcoin-price"},"display_name":{"type":"string","example":"Bitcoin Price"},"description":{"type":"string","example":"Current BTC price in USD"},"category":{"type":"string","enum":["bitcoin","calculated","eth","macro"],"example":"bitcoin"},"instrument":{"type":"string","enum":["futures","swap","options"],"description":"Present on a series that measures a futures, swap or options market (`futures`, `swap` or `options`), including a series PreReason calculates from one, and absent for every other series."}}},"MetricListResponse":{"type":"object","properties":{"count":{"type":"integer","example":26},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricListItem"}},"categories":{"type":"array","items":{"type":"string"},"example":["bitcoin","macro","calculated","treasury"]},"free_key":{"type":"string","description":"What each tier reads of a metric, in one sentence"},"pro_only_metrics":{"type":"array","items":{"type":"string"},"description":"The metrics only pro briefings use, read from the live briefings. A basic key reads their latest reading alone.","example":["oil-brent","treasury-3mo"]},"generated_at":{"type":"string","format":"date-time"}}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum requests per hour for your tier","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests remaining in current window","schema":{"type":"integer","example":55}},"X-RateLimit-Reset":{"description":"Unix timestamp when window resets","schema":{"type":"integer","example":1740200400}},"X-PreReason-Tier":{"description":"The plan of the API key the request was made with. Sent beside the rate limit headers on requests made with an API key, the short URLs included, and absent when the request carried no key or the plan could not be read.","schema":{"type":"string","enum":["free","basic","pro","enterprise"],"example":"basic"}}},"responses":{"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"Authentication required. Provide a valid API key."},"hint":{"type":"string","example":"Use \"Authorization: Bearer <api_key>\" or curl -u <api_key>:"},"signup":{"type":"string","example":"https://www.prereason.com/signup"},"how_to_get_key":{"type":"object","description":"What an agent can do about this 401 from where it stands: create a\nclaim, show one link to a human, poll until approved. REST only:\nMCP tool results carry no key path.\n","properties":{"summary":{"type":"string"},"claim_endpoint":{"type":"string","example":"https://api.prereason.com/api/agent/claims"},"signup_url":{"type":"string"},"docs":{"type":"string","example":"https://www.prereason.com/docs#agent-access"}}}}}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer realm=\"prereason\""}},"Link":{"schema":{"type":"string","example":"<https://www.prereason.com/docs#agent-access>; rel=\"help\""}}}},"PaymentRequired":{"description":"Payment required. The body is an x402 v2 payment quote naming this\nresource, its price in USDC, and the accepted networks. Pay and retry\nwith the payment header, or authenticate with an API key instead.\n","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","example":2},"error":{"type":"string","example":"Payment required"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Metric 'invalid-metric' not found"}}}}}},"RateLimitExceeded":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":0}},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-PreReason-Tier":{"$ref":"#/components/headers/X-PreReason-Tier"},"Retry-After":{"description":"Seconds until rate limit resets","schema":{"type":"integer","example":3600}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"RATE_LIMITED"},"message":{"type":"string","example":"Rate limit exceeded. Upgrade for higher limits."}}}}}}}}}