ExchangeRebel Token Efficiency 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: Token-Efficiency
paths:
  /toll/token-efficiency:
    get:
      tags:
      - Token-Efficiency
      summary: Payload Budget Check service catalog
      responses:
        '200':
          description: 'Success. Returns the service catalog: what a payload budget check includes, the price ($0.02 per call), the published criteria, the pinned test corpus, and the scope statement (a deterministic mechanical payload-budget check of the one payload you submitted, under token-efficiency/v1, counted exactly under the pinned cl100k_base tokenizer; no operation selects content by meaning and no model is called).'
      security: []
      operationId: getTollTokenEfficiency
      x-operation-id-source: derived
  /toll/token-efficiency/health:
    get:
      tags:
      - Token-Efficiency
      summary: Payload Budget Check service health
      responses:
        '200':
          description: Success. Returns service liveness and the report signer address.
      security: []
      operationId: getTollTokenEfficiencyHealth
      x-operation-id-source: derived
  /toll/token-efficiency/criteria:
    get:
      tags:
      - Token-Efficiency
      summary: The published payload budget check criteria
      responses:
        '200':
          description: 'Success. Returns the full published criteria (token-efficiency/v1): the input contract, the four shaping operations S-1..S-4 in order, the receipt and reconciliation rules, the pinned tokenizer (cl100k_base, gpt-tokenizer 4.1.0, SHA-256 pins in the Tokenizer Decision Record), the scope block, the kill line, and the pinned public test corpus identity; every report is reproducible from them.'
      security: []
      operationId: getTollTokenEfficiencyCriteria
      x-operation-id-source: derived
  /toll/token-efficiency/corpus:
    get:
      tags:
      - Token-Efficiency
      summary: The pinned public test corpus identity
      responses:
        '200':
          description: 'Success. Returns the public test corpus identity for token-efficiency/v1: corpus id token-efficiency-corpus/v1 and its SHA-256 pin 1f50ecdaf7965a3d79d3c277c17401a53e99e1887988fd7f737cf9f8ef0e4738 (the SHA-256 of the corpus''s canonical serialization, verifiable with the published harness). The corpus is buyer-runnable before paying.'
      security: []
      operationId: getTollTokenEfficiencyCorpus
      x-operation-id-source: derived
  /toll/token-efficiency/precheck:
    post:
      tags:
      - Token-Efficiency
      summary: Free headline payload-budget pre-check of one submitted payload
      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).
                payload:
                  type: string
                  description: The one payload to check, as text or as JSON text. Processed in memory only and never stored.
                budget_tokens:
                  type: integer
                  description: 'The token budget the payload must fit, counted under the published pinned tokenizer (cl100k_base). No default: a call without a valid budget_tokens is a free validation refusal.'
                keep_fields:
                  type: array
                  items:
                    type: string
                  description: Optional field paths protected from shaping operations.
                reserve_tokens:
                  type: integer
                  description: Optional reserve subtracted from budget_tokens to form the effective budget.
              required:
              - caller
              - payload
              - budget_tokens
      responses:
        '200':
          description: 'Success. Returns the headline only: the verdict line, the payload token count under the pinned tokenizer, and the excess figure. No shaped payload. When the caller''s free allowance is exhausted, the response is the /toll/token-efficiency/budget payment challenge instead.'
      security: []
      operationId: postTollTokenEfficiencyPrecheck
      x-operation-id-source: derived
  /toll/token-efficiency/budget:
    post:
      tags:
      - Token-Efficiency
      summary: Full signed payload-budget report for one submitted payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payload:
                  type: string
                  description: The one payload to check, as text or as JSON text. Processed in memory only and never stored.
                budget_tokens:
                  type: integer
                  description: 'The token budget the payload must fit, counted under the published pinned tokenizer (cl100k_base). No default: a call without a valid budget_tokens is a free validation refusal.'
                keep_fields:
                  type: array
                  items:
                    type: string
                  description: Optional field paths protected from shaping operations.
                reserve_tokens:
                  type: integer
                  description: Optional reserve subtracted from budget_tokens to form the effective budget.
              required:
              - payload
              - budget_tokens
      responses:
        '200':
          description: 'Success. Returns the full signed report: the fit verdict with the payload''s token count under the pinned tokenizer, the effective budget and the exact excess; where it does not fit, a shaped payload produced only by the four published mechanical operations (S-1..S-4, in that order) and a drop receipt whose deltas reconcile exactly. Submitted payloads are processed in memory only and are never stored.'
        '402':
          description: 'Payment Required (x402). A per-item fee: $0.02 per call — each payload you submit with a stated token budget is charged at $0.02; the payment includes one submitted payload (request body up to 262,144 bytes) and your stated budget, returned as (1) a signed fit verdict stating the payload''s token count under the tokenizer named in the verdict, your effective budget, and whether it fits or the exact excess; (2) where it does not fit, a shaped payload produced only by the mechanical operations published in token-efficiency/v1 — duplicate removal, empty-field removal, per-field truncation, tail truncation, in that order — and (3) a drop receipt listing every operation applied, by field, with token counts before and after that reconcile exactly with the shaped payload. No operation selects content by meaning; nothing is summarised, re-ranked, or rewritten by a model. If the payload cannot be brought within your stated budget under your stated constraints, you receive the unchanged payload with the verdict that it is not shapable within those constraints. A free pre-check returns the verdict line and the excess figure only. Submitted payloads are processed in memory only and are never stored; the payments ledger records only the payer, the time, the price, and the verdict. The response body carries the payment instructions in x402 v1 form: payTo (the operator''s Solana wallet), the amount (20000 USDC units = $0.02 per call) and a fresh memo. Pay in USDC on Solana with the memo attached via the Solana Memo program, then resubmit the same budget request with the payment transaction in the X-Payment-Tx header and ?toll_memo=<memo>, re-sending the payload 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.02'
      security:
      - x402Payment: []
      operationId: postTollTokenEfficiencyBudget
      x-operation-id-source: derived
  /toll/token-efficiency/metrics:
    get:
      tags:
      - Token-Efficiency
      summary: Payload Budget Check aggregate counters
      responses:
        '200':
          description: Success. Returns aggregate counters (paid checks, distinct payers, free pre-checks today). Aggregate only — no payer identities, no submitted payload content.
      security: []
      operationId: getTollTokenEfficiencyMetrics
      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.'