ExchangeRebel Chain Reconcile 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: Chain Reconcile
paths:
  /toll/chain-reconcile:
    get:
      tags:
      - Chain Reconcile
      summary: Chain Reconciliation service catalog
      responses:
        '200':
          description: 'Success. Returns the service catalog: what a multi-hop payment-chain reconciliation includes, the price ($0.05 per report), the published criteria (settlement-evidence/v1, multi-hop form), the pinned test corpus, and the scope statement (records leg only: submitted hop records are chain-verified and ancestor-cap arithmetic is applied over the submitted caps; no composite score).'
      security: []
      operationId: getTollChainReconcile
      x-operation-id-source: derived
  /toll/chain-reconcile/health:
    get:
      tags:
      - Chain Reconcile
      summary: Chain Reconciliation service health
      responses:
        '200':
          description: Success. Returns service liveness and the report signer address.
      security: []
      operationId: getTollChainReconcileHealth
      x-operation-id-source: derived
  /toll/chain-reconcile/criteria:
    get:
      tags:
      - Chain Reconcile
      summary: The published chain reconciliation criteria
      responses:
        '200':
          description: 'Success. Returns the full published criteria (settlement-evidence/v1, multi-hop form): the hop-record shape, the per-hop grading, the ancestor-cap arithmetic, the verdict set, and the pinned public test corpus identity; every report is reproducible from them.'
      security: []
      operationId: getTollChainReconcileCriteria
      x-operation-id-source: derived
  /toll/chain-reconcile/corpus:
    get:
      tags:
      - Chain Reconcile
      summary: The pinned public test corpus identity
      responses:
        '200':
          description: 'Success. Returns the public test corpus identity for chain reconciliation: corpus id chain-reconcile-corpus/v1 and its SHA-256 pin 0f62e010a21c0a70cacb1aa6cefe58cec9ddc8fd001bc900fd11626a4b2f9749 (the SHA-256 of the corpus''s canonical serialization, verifiable with the published harness). The corpus is buyer-runnable before paying.'
      security: []
      operationId: getTollChainReconcileCorpus
      x-operation-id-source: derived
  /toll/chain-reconcile/precheck:
    post:
      tags:
      - Chain Reconcile
      summary: Free headline pre-check of one submitted hop record set
      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).
                parent:
                  type: object
                  description: 'The chain parent: {reference (caller-chosen label, echoed never graded), capUnits (decimal string; the ancestor cap over all hops)}.'
                hops:
                  type: array
                  description: '1 to 20 hop records in chain order: {hop_id, signature (the on-chain payment transaction), expected {payTo, amountUnits, memo?}, capUnits (decimal string; this hop''s cap)}. Processed against the chain; hop-set content is never stored beyond the ledger''s closed field list.'
              required:
              - parent
              - hops
      responses:
        '200':
          description: 'Success. Returns assessability only: whether the hop record set is well-formed and chain-readable. No verdict and no cap verdict is returned. A malformed submission is refused free. When the caller''s free allowance is exhausted, the response is the /toll/chain-reconcile/reconcile payment challenge instead.'
      security: []
      operationId: postTollChainReconcilePrecheck
      x-operation-id-source: derived
  /toll/chain-reconcile/reconcile:
    post:
      tags:
      - Chain Reconcile
      summary: Full signed multi-hop payment-chain reconciliation report
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parent:
                  type: object
                  description: 'The chain parent: {reference (caller-chosen label, echoed never graded), capUnits (decimal string; the ancestor cap over all hops)}.'
                hops:
                  type: array
                  description: '1 to 20 hop records in chain order: {hop_id, signature (the on-chain payment transaction), expected {payTo, amountUnits, memo?}, capUnits (decimal string; this hop''s cap)}. Processed against the chain; hop-set content is never stored beyond the ledger''s closed field list.'
              required:
              - parent
              - hops
      responses:
        '200':
          description: 'Success. Returns the full signed report: every hop chain-verified (SETTLED-MATCH or the named mismatch), ancestor-cap arithmetic over the submitted caps, one verdict (CHAIN-SETTLED / CHAIN-UNSETTLED / CHAIN-MISMATCH / CHAIN-CAP-EXCEEDED, with the named hop), factors printed per hop, and an as-of timestamp. Submitted hop sets are never stored beyond the payments ledger''s closed field list.'
        '402':
          description: 'Payment Required (x402). A per-item fee: $0.05 per report - each submitted hop record set is charged at $0.05; the payment includes one multi-hop payment-chain reconciliation report — one submitted hop record set (a parent reference with its cap, plus per-hop payment references with the expected fields and the per-hop cap for each hop) — returned as per-hop chain verification via the settlement-evidence/v1 engine imported unchanged, ancestor-cap arithmetic over the submitted caps, one verdict (CHAIN-SETTLED / CHAIN-UNSETTLED with the named hop / CHAIN-MISMATCH with the named hop and the mismatching field named / CHAIN-CAP-EXCEEDED with the named hop), factors printed per hop, and an as-of timestamp. There is NO composite score. RECORDS LEG ONLY: this service reconciles submitted records against the chain; it does not delegate, enforce, sign, or move funds. Nothing about the submitted hop set is stored beyond 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 (50000 USDC units = $0.05 per report) 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 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.05'
      security:
      - x402Payment: []
      operationId: postTollChainReconcileReconcile
      x-operation-id-source: derived
  /toll/chain-reconcile/metrics:
    get:
      tags:
      - Chain Reconcile
      summary: Chain Reconciliation aggregate counters
      responses:
        '200':
          description: Success. Returns aggregate counters (paid reports, distinct payers, free pre-checks today). Aggregate only - no payer identities, no submitted hop-set content.
      security: []
      operationId: getTollChainReconcileMetrics
      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.'