ExchangeRebel Observatory Aggregates API

openapi: 3.2.0
info:
  title: ExchangeRebel — pay-per-call APIs for AI agents (x402 on…
  version: 1.0.0
  contact:
    name: 'ExchangeRebel (operator: Rebel Data)'
    url: https://exchangerebel.com
    email: sound.money.investing@gmail.com
  x-guidance: 'All paid operations use x402 on Solana: call without payment to get a 402 challenge (SOL recipient + USDC token account + fresh memo), pay with the memo attached via the Solana Memo program, then retry with header X-Payment-Tx: <signature> and ?toll_memo=<memo>. Challenges are dual-version: the PAYMENT-REQUIRED header carries the x402 v2 PaymentRequired object and the response body carries the same challenge in x402 v1 form for compatibility. Free operations (security: []) include each service''s /health catalog with full response shapes. Prices in x-payment-info are USD per call unless the summary says otherwise (RPC is per 1,000-request block; Telegram provisioning is per bot-month; transcription is per minute of audio).'
  description: '67 data and utility APIs behind x402 tolls, settled in SOL or USDC on Solana. Call a paid endpoint without payment to receive a 402 x402 challenge (recipient + fresh memo), pay with the memo attached via the Solana Memo program, then retry with the X-Payment-Tx header and toll_memo query parameter. Free catalog/health endpoints are marked without x-payment-info. Full catalogs: GET /toll/discovery and each service''s /health.'
servers:
- url: https://exchangerebel.com
tags:
- name: Observatory Aggregates
paths:
  /toll/observatory:
    get:
      tags:
      - Observatory Aggregates
      summary: Observatory Aggregates service catalog
      responses:
        '200':
          description: 'Success. Returns the service catalog: what an aggregate snapshot includes, the price ($0.005 per snapshot), the published criteria (observatory-aggregates/v1), the pinned test corpus, and the scope statement (aggregate counts of our own front door only - discovery calls, challenged-but-unpaid ops, requested-but-nonexistent tools and paths; counts only, never client identity, purchases, or usage patterns; scope: our doorway only).'
      security: []
      operationId: getTollObservatory
      x-operation-id-source: derived
  /toll/observatory/health:
    get:
      tags:
      - Observatory Aggregates
      summary: Observatory Aggregates service health
      responses:
        '200':
          description: Success. Returns service liveness and the report signer address.
      security: []
      operationId: getTollObservatoryHealth
      x-operation-id-source: derived
  /toll/observatory/criteria:
    get:
      tags:
      - Observatory Aggregates
      summary: The published observatory aggregates criteria
      responses:
        '200':
          description: 'Success. Returns the full published criteria (observatory-aggregates/v1): the catalogue of snapshots with each counting rule and threshold, the scope label (''our doorway only''), the confidentiality boundary, and the pinned public test corpus identity; every snapshot is reproducible from them.'
      security: []
      operationId: getTollObservatoryCriteria
      x-operation-id-source: derived
  /toll/observatory/catalogue:
    get:
      tags:
      - Observatory Aggregates
      summary: The free snapshot catalogue
      responses:
        '200':
          description: 'Success. Returns the free snapshot catalogue: every snapshot id offered, its counting rule, its minimum-count threshold, and its price ($0.005 per snapshot), before any payment.'
      security: []
      operationId: getTollObservatoryCatalogue
      x-operation-id-source: derived
  /toll/observatory/corpus:
    get:
      tags:
      - Observatory Aggregates
      summary: The pinned public test corpus identity
      responses:
        '200':
          description: 'Success. Returns the public test corpus identity for observatory-aggregates/v1: corpus id observatory-aggregates-corpus/v1 and its SHA-256 pin b57ae99d18f547588438fd2e562247f08750456aac5f204ae2c3350277f439d0 (the SHA-256 of the corpus''s canonical serialization, verifiable with the published harness). The corpus is buyer-runnable before paying.'
      security: []
      operationId: getTollObservatoryCorpus
      x-operation-id-source: derived
  /toll/observatory/precheck:
    post:
      tags:
      - Observatory Aggregates
      summary: Free pre-check of one snapshot request (validation only)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                caller:
                  type: string
                  description: Solana base58 wallet of the operator; keys the free allowance (100/day per wallet).
                catalogue_id:
                  type: string
                  description: One catalogue id from GET /catalogue (e.g. discovery-total).
                window:
                  type: object
                  description: 'UTC-day window, inclusive: { start: YYYY-MM-DD, end: YYYY-MM-DD }, max 366 days.'
              required:
              - caller
              - catalogue_id
              - window
      responses:
        '200':
          description: 'Success. Returns assessability only: whether the catalogue id exists and the window is well-formed. No counts and no grade are returned. When the caller''s free allowance is exhausted, the response is the /toll/observatory/snapshot payment challenge instead.'
      security: []
      operationId: postTollObservatoryPrecheck
      x-operation-id-source: derived
  /toll/observatory/snapshot:
    post:
      tags:
      - Observatory Aggregates
      summary: One signed aggregate snapshot ($0.005)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                catalogue_id:
                  type: string
                  description: One catalogue id from GET /catalogue (e.g. discovery-total).
                window:
                  type: object
                  description: 'UTC-day window, inclusive: { start: YYYY-MM-DD, end: YYYY-MM-DD }, max 366 days.'
              required:
              - catalogue_id
              - window
      responses:
        '200':
          description: 'Success. Returns the signed aggregate snapshot: the counts computed by the published counting rule for the named catalogue id and window, the window bounds, the threshold applied, and the scope label (''our doorway only''); below-threshold snapshots answer NOT-OFFERED with the threshold stated and the count never printed; an empty window answers EMPTY-WINDOW.'
        '402':
          description: 'Payment Required (x402). A per-item fee: $0.005 per snapshot - the payment includes one aggregate snapshot — the counts computed by the published counting rule for the one catalogue id and the one window you name, the window''s bounds, the threshold applied, and the scope label (''our doorway only''). Counts only: no client identity, no per-client rows, no purchase or usage-pattern detail. If the snapshot''s total is below its published minimum-count threshold, the delivery is a NOT-OFFERED answer stating the threshold and the fact of suppression — the count itself is never printed. If the window holds no front-door events, the delivery is an EMPTY-WINDOW stated absence, not zeros. Factors printed; no composite score. Nothing is stored beyond the snapshot answer and the payments ledger''s closed field list. The response body carries the payment instructions in x402 v1 form: payTo (the operator''s Solana wallet), the amount (5000 USDC units = $0.005 per snapshot) and a fresh memo. Pay in USDC on Solana with the memo attached via the Solana Memo program, then resubmit the same request with the payment transaction in the X-Payment-Tx header and ?toll_memo=<memo>, re-sending the snapshot request in the request body. The PAYMENT-REQUIRED response header carries the same object in x402 v2 form.'
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
      security:
      - x402Payment: []
      operationId: postTollObservatorySnapshot
      x-operation-id-source: derived
  /toll/observatory/metrics:
    get:
      tags:
      - Observatory Aggregates
      summary: Observatory Aggregates aggregate counters
      responses:
        '200':
          description: Success. Returns aggregate counters (paid snapshots, distinct payers, free pre-checks today). Aggregate only - no payer identities, no snapshot content.
      security: []
      operationId: getTollObservatoryMetrics
      x-operation-id-source: derived
components:
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: X-Payment-Tx
      description: 'x402 toll payment proof: the Solana transaction signature of a payment carrying the memo from the 402 challenge; send together with ?toll_memo=<memo>. Payment itself is made on-chain in SOL or USDC to the recipient named in the challenge.'