Horizon Pulse Verified brief API

openapi: 3.2.0
info:
  title: Horizon Pulse Verified brief API
  version: 1.1.0
  termsOfService: https://horizonpulse.dev/terms/buyer
  summary: Pay-per-call APIs for AI agents, settled in USDC on Base, Solana or Polygon, or RLUSD on the XRP Ledger, with x402.
  description: 'Pay-per-call APIs for AI agents, paid in USDC on Base, Solana or Polygon, or RLUSD on the XRP Ledger, with x402: web search, page fetch and extract, PDF to text, an HTTP proxy, and crypto market data. No signup or API key.


    On Base, you only pay for a successful response; errors are not charged except where an operation says so (for /api/tx-status, a not_found status is a charged answer; poll again after pollAgainSeconds). These no-charge statements are made for USDC on Base. On USDC on Solana, and RLUSD on the XRP Ledger, a refused or failed request may still be charged. charged: false means Horizon Pulse did not settle the payment; on USDC on Solana, and RLUSD on the XRP Ledger, this is not a guarantee that no funds moved. Every paid operation carries `x-payment-info` with the exact price, asset, network and payTo of its Base entry; these match the 402 challenge and https://horizonpulse.dev/.well-known/x402. The 402 challenge also offers the same price in USDC on Solana mainnet (`exact`, network solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, USDC mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, payTo BjY98A6dS3GGLZdz2zHy8wK7XAwnQgNhCc66mfmBTRPz, PayAI facilitator https://facilitator.payai.network), and in native USDC on Polygon PoS mainnet (`exact`, network eip155:137, USDC 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359, payTo 0x5b32c973596078a967562ca652761404f19be0e9, facilitator: Coinbase CDP), and in RLUSD on the XRP Ledger mainnet (`exact`, network xrpl:0, currency RLUSD = 524C555344000000000000000000000000000000, issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De, payTo r3FbirL83RAB2CwnUdxE5pCohMkuo6LQcf, verified on the validated ledger). Recorded example responses (fixed input, dated, informational; not paid operations): GET /api/demo/{route}.


    Agent integration: step-by-step skill at https://horizonpulse.dev/skill.md; guide with MCP setup at https://horizonpulse.dev/agents (hosted MCP at https://horizonpulse.dev/mcp for x402-aware clients, plus a local stdio MCP server in the repo''s mcp/ folder that pays from your own wallet with spend caps).


    Services for API owners (web pages, not API operations; not paid via x402): Bazaar listing fix at https://horizonpulse.dev/listing-fix; agent promotion at https://horizonpulse.dev/agent-promotion.'
  contact:
    name: Horizon Pulse
    email: horizonpulse.co@proton.me
    url: https://horizonpulse.dev
  x-guidance: 'Read PAYMENT-REQUIRED (base64 JSON). Pay exact USDC on Base (CDP), Solana (PayAI feePayer), Polygon, or RLUSD on XRPL at the listed payTo. Unpaid samples: /api/demo/{route}. Skill: /skill.md. Hosted MCP: /mcp (Base USDC only).'
servers:
- url: https://horizonpulse.dev
  description: Production
security:
- x402: []
tags:
- name: Verified brief
paths:
  /api/research/report/brief:
    get:
      operationId: getResearchReportBrief
      tags:
      - Verified brief
      summary: 'Verified brief, three question types only: Base or Ethereum gas (on-chain…'
      description: 'Verified brief (schema brief-verified/1), on-chain live values and x402 spec facts only: answer plus 2-8 claims, each with an evidence array (verbatim quote, URL, retrieval time, body hash, offset; or chain, block and block time for on-chain reads). For USDC on Base: charged only if >=2 claims are confirmed (2 publishers, 2 nodes, or 2 x402 spec documents) and every quote verifies; otherwise unpaid. Contract: horizonpulse.dev/contracts/brief-verified. Not advice.


        Price: $1 USDC (1000000 atomic), USDC on Base only: x402 v2 `exact` on Base (eip155:8453) only; other networks are refused before payment. The research runs before settlement, and the payment settles only if the brief passes the contract; otherwise 422 and nothing is charged for USDC on Base. Out-of-scope questions get 422 before any payment. Contract: https://horizonpulse.dev/contracts/brief-verified. Terms: https://horizonpulse.dev/premium-terms. Unpaid sample: https://horizonpulse.dev/api/demo/brief-verified. Not payable over MCP: the hosted MCP tool verified_brief returns this same unpaid 402 challenge.'
      x-premium-payment-info:
        protocol: x402
        x402Version: 2
        scheme: exact
        network: eip155:8453
        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        assetSymbol: USDC
        decimals: 6
        priceUsd: $1
        amount: '1000000'
        payTo: '0x5b32c973596078a967562ca652761404f19be0e9'
        facilitator: https://api.cdp.coinbase.com/platform/v2/x402
        discovery: https://horizonpulse.dev/.well-known/x402
        contract: https://horizonpulse.dev/contracts/brief-verified
        terms: https://horizonpulse.dev/premium-terms
      parameters:
      - name: q
        in: query
        required: true
        description: Question about Base or Ethereum gas, USDC supply on Ethereum and Base, or an x402 spec fact. Anything else is refused with 422 before payment. No personal data.
        schema:
          type: string
        example: How much USDC is in circulation?
      responses:
        '200':
          description: Verified brief (schema brief-verified/1). Charged.
          content:
            application/json:
              schema:
                type: object
        '402':
          description: 'Payment required: PAYMENT-REQUIRED header, $1 USDC on Base only.'
          content:
            application/json:
              schema:
                type: object
        '422':
          description: Out of scope, or the brief did not pass the contract. Reason codes only. Nothing charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable or daily budget reached. Nothing charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Error body. Errors are not charged unless the route description says otherwise (e.g. /api/http passes upstream 4xx/5xx back as data).
      required:
      - ok
      - error
      properties:
        ok:
          const: false
        error:
          type: string
        code:
          type: string
          description: Stable machine-readable error code, where the route has one.
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment payload (base64 JSON), built from the 402 PAYMENT-REQUIRED challenge. No account or API key. See https://www.x402.org/.
externalDocs:
  description: 'Agent guide: discovery, the x402 pay flow, skill file and MCP setup'
  url: https://horizonpulse.dev/agents