Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: PreReason Treasury Holdings API
version: 1.0.0
description: 'Financial market data for AI agents, paid per request with no API key (x402
or MPP, USDC on Base) or read with a key: economic indicators, Treasury
yields and rates, FX, commodities, listed companies'' financial statements
and Bitcoin, each served as a briefing with the interpretation done.
PreReason returns market briefings with the interpretation already done:
trends, regime classification and confidence scores. Markdown by default,
which costs about
40 percent fewer tokens than JSON. Add ?format=json for structured output.
Coverage is macro, rates, bonds, FX, commodities, listed companies and
Bitcoin: the Fed balance sheet, M2, net liquidity, Treasury yields and
auctions, the dollar, oil and gas inventories, metals and grains, company
briefings, Bitcoin price, network and ETF flows, and cross asset
correlations.
GET /api/briefings is the live catalogue, with the tier each briefing
needs, and GET /api/metrics lists the individual series. Neither needs a key.
Not every endpoint needs one. Each operation below declares its own rule,
and the catalogue endpoints, the health and status endpoints and POST
/api/mcp are open. A briefing needs either an API key, sent as
Authorization: Bearer or X-API-Key, or a payment for that single call:
request a priced endpoint without a key and the 402 quotes both x402 and
MPP, USDC on Base. Free keys at https://www.prereason.com/signup, and an
agent with no browser of its own can earn one through the claim flow at
https://www.prereason.com/auth.md. Full reference at
https://www.prereason.com/docs.
Briefings are built from these providers'' data: Federal Reserve Bank of
New York, Board of Governors of the Federal Reserve System, U.S. Department
of the Treasury, Treasury International Capital (TIC), U.S. Treasury Fiscal
Data, CFTC, EIA, BIS, SEC EDGAR, FRED, mempool.space and CoinGecko, and 24
more, each named with every value it supplies (every provider is listed at
https://www.prereason.com/data-sources). Freshness ranges from near real
time to monthly depending on the series, and ETF market data updates every
15 minutes during market hours. Powered by CoinGecko. This product uses the
FRED API but is not endorsed or certified by the
Federal Reserve Bank of St. Louis.'
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
security:
- BearerAuth: []
tags:
- name: Treasury Holdings
description: 'Per-company corporate Bitcoin treasury holdings with provenance.
The btc.treasury briefing interprets and ranks the top holders; these
endpoints are the lookup surface for every tracked company, with the
source, as-of date and filing URL attached to each figure.'
paths:
/api/treasuries:
get:
tags:
- Treasury Holdings
summary: Corporate Bitcoin treasury holdings for every tracked public company
description: 'Corporate Bitcoin treasury holdings data for every tracked public
company, paid per request with no API key.
Every tracked company with its holding, source and as-of date. Read with a key on the Pro plan or above.
**Precision is not uniform, and the response says so per row.**
A figure the company filed with the SEC is public record: `precision` is
`exact`, `btc_exact` carries the number, and `filing_url` links the
document. A figure published by CoinGecko is an estimate: `precision` is
`estimate`, `btc_exact` is `null`, and only the rounded `btc_display` is
given. Reading `btc_exact` alone can never mistake an estimate for a
filed figure.
Where our two sources disagreed materially, someone read the filing and
the verdict appears in `adjudication` with its evidence.
Rows do not sum to `total_btc_exact`, because estimate rows are rounded.
The roster is a curated subset of listed treasury holders, so the total
understates the market-wide figure.
**Financing, from filings.** Each row carries `financing_summary`, or
`null`: the senior claims the company''s own latest periodic SEC filing
states (debt principal plus preferred stock at its liquidation
preference), the same figure per BTC in that filing, the bitcoin''s share
of total assets and what falls due within 24 months, each as of the
filing''s balance sheet date and with the filing''s link. These are filed
figures, served exact, and they keep their own date: the holding beside
them may be newer. `financing.companies_with_filed_financing` counts the
rows that carry one. A company that files in yen on EDINET (Metaplanet)
is in dollars like the rest, converted at one stored rate of its
balance sheet date; its summary''s `filed_currency` carries its senior
claims as filed in yen and that rate with its source and date
(`filed_currency` is `null` for a company that files in dollars), and
its summary''s `citation` carries EDINET''s source citation under the
Public Data License 1.0, as EDINET''s terms ask (`null` for an SEC
filer).
**mNAV.** Each row carries `mnav_summary`, or `null`: market value
over the value of the bitcoin held, as `value`, with its `basis` and
its `as_of` date. The basis is `in house` (derived from the company''s
filed share count, a stored share close and the served holding) or,
for a company with no in house figure, `CoinGecko` (CoinGecko''s own
published figure, named as CoinGecko''s). The two are computed
differently and are not comparable to the hundredth. A figure is shown
only where the bitcoin is worth at least a tenth of the market value
(10 or less), and a CoinGecko figure only at 0.25 or more.
`mnav.companies_with_mnav` counts the rows that carry
one, and the company route carries the inputs or the reason.
**Withheld.** `withheld` lists the tracked companies whose count from
our source is above the total the company itself reported, and those
whose count PreReason read from a filing does not match that filing,
each with `ticker`, `company_name`, `reason` and `evidence_filing` (the
filing the reason cites: `form`, `accession`, `filed`, `url`). None of
them is in `holdings` or in `total_btc_exact`, and no count is shown
for them. It is an empty list when none is withheld.'
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/treasuries/{ticker}:
get:
tags:
- Treasury Holdings
summary: One public company's Bitcoin treasury holding
description: 'One public company''s Bitcoin treasury holding, paid per request with no
API key. Single-company lookup with the same precision and provenance rules as
the list endpoint. Read with a key on the Pro plan or above. A 404 means the company is not on the tracked roster. It is **not**
evidence that the company holds no Bitcoin. A withheld company (the list''s `withheld`) answers 200 with `holding:
null` and `withheld` (its reason and the filing the reason cites), its
`financing` as below, and no `mnav`. `financing` carries what the company''s own latest periodic SEC filing
states, as of its balance sheet date: debt by instrument, preferred
classes at their liquidation preference, the maturity table, the
bitcoin count in the same filing, the senior claims these add up to,
and the financing filings made since, which are listed and never added
in. It is `null`, with `financing_note` saying why, for a company with
no SEC filing, or with no filing reading served (none is stored, or
its newest is held for review). A company that files in yen is read from its own annual or half year
report on EDINET (Metaplanet). Its `financing` has the same shape, in
dollars: every figure is the filed yen amount converted at one stored
rate, the Federal Reserve Board''s H.10 rate of the balance sheet date. `financing.filed_currency` carries that rate with its source and date
and every amount as filed in yen (`null` for a company that files in
dollars), and `financing.citation` carries EDINET''s source citation
under the Public Data License 1.0, as EDINET''s terms ask (`null` for
an SEC filing). Ratios are taken on the yen amounts, so no rate enters them. Such a report tags no bitcoin count: the count is read from the
sentence of its text that states the holding at the balance sheet
date, `financing.btc.count_basis` says so, and it is used only where
it passes the same check as a tagged count. Filings made after the
balance sheet date are not listed for an EDINET filer. For Strategy, two later statements from its own 8-Ks ride beside the
filing''s figures, each with the 8-K''s date and link: `atm_capacity`,
the amount each at the market program still has available for issuance
and sale, and `btc_stated_since`, the bitcoin count the 8-K states. Neither is added into the figures above; the per BTC figures still
divide by the count in the periodic filing. Both are empty for every
other company. `mnav` sits beside `financing`, under its own key, because it is not a
filing''s figure. Its `basis` says which of two figures it is, and the
two are never mixed. With `basis: in house` it is derived for the newest session a share
close is stored for: market value (the shares outstanding the latest
10-Q or 10-K states on its cover, times the stored close of the listed
share) over the value of the bitcoin held (the served holding times
the stored BTC price that session), and an enterprise value variant
that adds the filing''s debt and preferred stock and takes off its
cash. Every input is served with its own source and date, and they
differ: the share count is the filing''s and can be months older than
the close. Where the served holding is an estimate, the ratio uses it
as displayed. An in house figure stands for 7 days after its session. With `basis: CoinGecko` it is CoinGecko''s own published figure
(`m_nav`), for a company with no in house figure: a company with no
SEC filing reading, a 20-F filer, no stored close, or share classes
not reviewed. It carries `source: CoinGecko`, the CoinGecko entity it
was read for, the day and time it was read, and `why_not_in_house`. The share count and the method behind it are CoinGecko''s, so it is not
comparable to the hundredth with an in house figure. It is read once a
day and shown only while it is about a day old, and only at 0.25 or
more: under that `mnav` is `null` and `mnav_note` says so. Powered by
CoinGecko.'
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
components:
responses:
PaymentRequired:
description: 'Payment required. The body is an x402 v2 payment quote naming this
resource, its price in USDC, and the accepted networks. Pay and retry
with the payment header, or authenticate with an API key instead.
'
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
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
claim, show one link to a human, poll until approved. REST only:
MCP tool results carry no key path.
'
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"
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'API key as Bearer token. Get your key at [prereason.com/signup](https://www.prereason.com/signup).
```
Authorization: Bearer pr_live_xxx
```
'
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'The same API key in its own header, for clients that cannot set `Authorization`.
```
X-API-Key: pr_live_xxx
```
'
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