prereason-com Agent access API

openapi: 3.2.0
info:
  title: PreReason Agent access 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: Agent access
  description: 'How an agent with no key gets one from inside its own session. The agent

    creates a claim, shows one link to the human who owns it, and polls until

    the human has signed in and approved; the key it then receives belongs to

    that human''s account. No key is issued without the approval. The MCP

    bridge (npx -y @prereason/mcp) runs the same flow for an MCP client; the

    hosted MCP server hands out no key.'
paths:
  /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

        (PR-XXXX-XXXX) and a one time claim_token only the agent holds. Show the

        human approve_url; they sign in (or create the account there) and click

        Approve. Then poll GET /api/agent/claims/{code} with the claim_token as

        a Bearer until status is approved; that response carries the api_key

        once. The key is attached to the approving human''s account and named

        "Agent: ".


        Limits: 5 claims an hour per address, 20 pending per address, 2,000

        pending globally (503 with Retry-After). A claim lives 15 minutes; the

        approval page can extend it to at most 60 minutes from creation.'
      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 . Answers status pending (keep

        polling every poll_interval seconds), approved with the api_key on the

        first poll after approval, delivered on every later poll (no key in the

        body), denied, or expired. An unknown code and a wrong token are the

        same 404. 30 polls a minute per address.'
      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
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).


        ```

        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