openapi: 3.1.0
info:
  title: FeedOracle RLUSD Evidence API
  version: 3.2.0
  description: Evidence-grade risk signals for RLUSD. Hash-anchor proofs (Polygon+XRPL),
    circuit breaker, CCI scoring. Data infrastructure only.
  contact:
    email: support@feedoracle.io
  license:
    name: Proprietary
    url: https://feedoracle.io/legal
servers:
- url: https://api.feedoracle.io
  description: Primary API
- url: https://feedoracle.io
  description: Legacy (deprecated - sunset 2026-06-30)
tags:
- name: RLUSD
  description: RLUSD transparency (public)
- name: Circuit
  description: Circuit breaker (reserve_guard_v1)
- name: Integrity
  description: Hash-anchor proofs (zk_component=false)
paths:
  /api/v3/rlusd/status:
    get:
      tags:
      - RLUSD
      operationId: getRlusdStatus
      summary: RLUSD service status
      description: Returns service status with meta envelope. Use to check API health
        and latest attestation report.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdStatusEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
  /api/v3/rlusd/supply/breakdown:
    get:
      tags:
      - RLUSD
      operationId: getRlusdSupplyBreakdown
      summary: Supply breakdown by chain
      description: Returns total/XRPL/ETH supply as strings with decimals field.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdSupplyBreakdown'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v3/rlusd/peg/quality:
    get:
      tags:
      - RLUSD
      operationId: getRlusdPegQuality
      summary: Peg quality from Bitstamp
      description: 'Bid/ask-based peg deviation (bps + pct), spread, volume. Source:
        Bitstamp ticker.'
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdPegQuality'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v3/rlusd/cci:
    get:
      tags:
      - RLUSD
      operationId: getRlusdCciCompact
      summary: CCI compact score
      description: Compliance Confidence Index with components and penalty_log.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdCciCompact'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v3/rlusd/risk/cci:
    get:
      tags:
      - RLUSD
      operationId: getRlusdCciDetailed
      summary: CCI detailed score
      description: Detailed CCI with subscores, weights, and warnings.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdCciDetailed'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v3/rlusd/evidence/latest:
    get:
      tags:
      - RLUSD
      - Integrity
      operationId: getRlusdEvidenceLatest
      summary: Latest evidence pack
      description: Hash-anchor integrity proof + circuit breaker checks + compliance
        flags. Contains verify handle for hash verification.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdEvidencePack'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v3/rlusd/holders:
    get:
      tags:
      - RLUSD
      operationId: getRlusdHolders
      summary: Holder distribution by chain
      description: Returns holder count per chain (ETH + XRPL) with top10 concentration.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdHolders'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v3/rlusd/webhooks/events:
    get:
      tags:
      - RLUSD
      operationId: getRlusdWebhookEvents
      summary: Webhook events catalog
      description: Lists webhook events, severity, cooldowns, retry policy, signature
        scheme.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdWebhookCatalog'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/v3/rlusd/verify/{hash}:
    get:
      tags:
      - RLUSD
      - Integrity
      operationId: verifyRlusdHash
      summary: Verify content hash
      description: Verify snapshot hash against on-chain anchors (Polygon + XRPL).
      security: []
      parameters:
      - name: hash
        in: path
        required: true
        description: SHA-256 content hash (64 hex chars)
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{64}$
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RlusdVerifyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/v1/circuit/status:
    get:
      tags:
      - Circuit
      operationId: getCircuitStatus
      summary: Circuit breaker status
      description: Reserve guard (reserve_guard_v1) status with 4 health checks.
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircuitStatus'
        '500':
          $ref: '#/components/responses/ServerError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/circuit/health:
    get:
      tags:
      - Circuit
      operationId: getCircuitHealth
      summary: Circuit breaker health
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircuitHealth'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/v1/zk/status:
    get:
      tags:
      - Integrity
      operationId: getIntegrityStatus
      summary: Integrity circuit status
      description: 'Runtime status of hash-anchor circuit. Note: zk_component=false
        means hash-anchor only, not ZK proof.'
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrityStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/v1/zk/health:
    get:
      tags:
      - Integrity
      operationId: getIntegrityHealth
      summary: Integrity circuit health
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircuitHealth'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/v1/zk/attestation/latest:
    get:
      tags:
      - Integrity
      operationId: getIntegrityAttestationLatest
      summary: Latest on-chain anchor attestation
      description: Polygon anchor status (tx_hash, contract, min_ratio_bps, threshold_passed).
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrityAttestation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
    MetaEnvelope:
      type: object
      properties:
        api_version:
          type: string
        dataset_version:
          type: string
        schema_version:
          type: string
        build_id:
          type: string
        build_time:
          type: string
        backend_node:
          type: string
        uptime_s:
          type: integer
    RlusdStatusData:
      type: object
      properties:
        disclaimer:
          type: string
        latest_ratio:
          type: number
        latest_report:
          type: string
        latest_supply:
          type: integer
        reports_available:
          type: integer
        status:
          type: string
    RlusdStatusEnvelope:
      type: object
      required:
      - service
      - meta
      - data
      - warnings
      properties:
        service:
          type: string
        meta:
          $ref: '#/components/schemas/MetaEnvelope'
        data:
          $ref: '#/components/schemas/RlusdStatusData'
        warnings:
          type: array
          items:
            type: string
    RlusdSupplyData:
      type: object
      properties:
        decimals:
          type: integer
        total:
          type: string
        xrpl:
          type: string
        eth:
          type: string
        xrpl_pct:
          type: number
        eth_pct:
          type: number
    RlusdSupplyBreakdown:
      type: object
      required:
      - service
      - meta
      - data
      properties:
        service:
          type: string
        meta:
          $ref: '#/components/schemas/MetaEnvelope'
        data:
          $ref: '#/components/schemas/RlusdSupplyData'
    RlusdCciCompact:
      type: object
      required:
      - cci_score
      - grade
      - components
      - penalty_log
      properties:
        cci_score:
          type: number
        grade:
          type: string
        max_score:
          type: number
        components:
          type: object
        penalty_log:
          type: object
        disclaimer:
          type: object
        timestamp:
          type: string
        supply_check:
          type: object
    RlusdCciDetailed:
      type: object
      required:
      - cci_score
      - grade
      - subscores
      - weights
      properties:
        cci_score:
          type: number
        grade:
          type: string
        version:
          type: string
        rules_version:
          type: string
        subscores:
          type: object
        weights:
          type: object
        warnings:
          type: array
        timestamp:
          type: string
    RlusdEvidencePack:
      type: object
      required:
      - as_of
      - guard
      - circuit_breaker
      - integrity_proof
      - snapshot
      - disclaimer
      properties:
        as_of:
          type: string
        guard:
          type: object
        circuit_breaker:
          type: object
        compliance:
          type: object
        integrity_proof:
          type: object
        snapshot:
          type: object
        disclaimer:
          type: object
        schema_version:
          type: string
        request_id:
          type: string
        served_by:
          type: string
    RlusdHolders:
      type: object
      required:
      - chains
      - total_holders
      - timestamp
      properties:
        chains:
          type: object
          properties:
            eth:
              type: object
            xrpl:
              type: object
        total_holders:
          type: integer
        timestamp:
          type: string
    RlusdVerifyResponse:
      type: object
      properties:
        valid:
          type: boolean
        content_hash:
          type: string
        snapshot_id:
          type: string
        anchors:
          type: object
    RlusdPegQuality:
      type: object
      required:
      - service
      - meta
      - data
      properties:
        service:
          type: string
        meta:
          $ref: '#/components/schemas/MetaEnvelope'
        data:
          type: object
    RlusdWebhookCatalog:
      type: object
      required:
      - events
      - catalog
      - retry_policy
      - signature
      properties:
        events:
          type: array
          items:
            type: string
        catalog:
          type: object
        retry_policy:
          type: object
        signature:
          type: string
    CircuitStatus:
      type: object
      required:
      - status
      - action
      - checks
      properties:
        status:
          type: string
        status_code:
          type: integer
        action:
          type: string
        asset:
          type: string
        checks:
          type: object
        metrics:
          type: object
        signature:
          type: string
        timestamp:
          type: string
    CircuitHealth:
      type: object
      properties:
        status:
          type: string
        service:
          type: string
    IntegrityStatus:
      type: object
      required:
      - circuit
      - runtime_version
      - status
      properties:
        circuit:
          type: string
        runtime_version:
          type: string
        status:
          type: string
    IntegrityAttestation:
      type: object
      required:
      - tx_hash
      - contract
      - chain_id
      - min_ratio_bps
      - threshold_passed
      properties:
        tx_hash:
          type: string
        contract:
          type: string
        chain_id:
          type: integer
        min_ratio_bps:
          type: integer
        threshold_passed:
          type: boolean
        explorer_url:
          type: string
        block_number:
          type: integer
        block_timestamp_utc:
          type: string
        bound_snapshot_hash:
          type: string
        age_seconds:
          type: integer
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limited (10 req/min)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'