prereason-com Webhooks API

openapi: 3.2.0
info:
  title: PreReason Webhooks 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: Webhooks
  description: 'Change events, pushed by webhook to an account''s registered addresses or

    read from the feed. What changed since a cursor: a live briefing''s state label, a tracked

    release, and, for the companies a read names, newer figures, an event

    driven situation turning on, and filed news. A key on the

    Basic or Pro plan reads its plan''s events; a caller with no key pays

    per read.'
paths:
  /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

        briefing''s state label changing, a tracked release becoming known

        (the Fed''s weekly balance sheet, the FOMC statement and target range,

        Treasury auction results, the EIA''s weekly crude oil and natural gas

        stocks, ECB and Bank of Japan policy rates), and, for the companies a

        read names, figures stored for a newer period, an event driven

        situation the company briefing reports turning on, and filed news (for

        the USA: an 8-K''s material events, leadership changes and results).

        Each event says what

        changed, when it happened, when PreReason knew it, the rule and where

        to fetch the briefing or metric it concerns; it carries no value.


        With no cursor the read starts 24 hours back; each answer''s

        `next_cursor` is where the next read starts. Events are kept 30 days.

        A company''s events reach only a read that names the company in

        `companies`. `kinds` narrows company news; ownership reports come only

        to a read that names them.


        A key on the Basic or Pro plan reads its plan''s events and is never

        charged here. A caller with no key pays per read. A malformed cursor,

        an unknown event type, a malformed company, more than 200 companies

        or an unknown news kind answers 400, and nothing is charged.'
      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
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