openapi: 3.0.3
info:
  title: FeedOracle API
  version: 1.0.0
  description: Enterprise blockchain sustainability data with DORA-supporting controls.
  contact:
    email: contact@feedoracle.io
  license:
    name: Proprietary
servers:
  - url: https://feedoracle.io
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Carbon
  - name: Disclosure
  - name: WorldBank
  - name: Grid
  - name: Energy
  - name: Trade
  - name: Macro
  - name: Memory
  - name: NFT
  - name: DAP
  - name: A2A
paths:
  /api/v1/carbon/chains:
    get:
      tags: [Carbon]
      summary: All blockchain carbon data
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /api/v1/carbon/summary:
    get:
      tags: [Carbon]
      summary: Carbon summary statistics
      responses:
        '200':
          description: Success
  /api/v3/disclosure/networks:
    get:
      tags: [Disclosure]
      summary: MiCA Art. 66 network list
      responses:
        '200':
          description: Success
  /api/v3/disclosure/sustainability/{symbol}:
    get:
      tags: [Disclosure]
      summary: Sustainability data for network
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /worldbank/health:
    get:
      tags: [WorldBank]
      summary: Service health
      security: []
      responses:
        '200':
          description: Success
  /worldbank/gdp:
    get:
      tags: [WorldBank]
      summary: GDP data for major economies
      responses:
        '200':
          description: Success
  /worldbank/country/{code}:
    get:
      tags: [WorldBank]
      summary: Country indicators
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /grid/health:
    get:
      tags: [Grid]
      summary: Service health
      security: []
      responses:
        '200':
          description: Success
  /grid/uk/now:
    get:
      tags: [Grid]
      summary: UK realtime carbon intensity
      responses:
        '200':
          description: Success
  /grid/uk/generation:
    get:
      tags: [Grid]
      summary: UK generation mix
      responses:
        '200':
          description: Success
  /grid/country/{code}:
    get:
      tags: [Grid]
      summary: Country carbon data
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /energy/health:
    get:
      tags: [Energy]
      summary: Service health
      security: []
      responses:
        '200':
          description: Success
  /energy/country/{iso3}:
    get:
      tags: [Energy]
      summary: Country energy profile
      parameters:
        - name: iso3
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /energy/renewable/{iso3}:
    get:
      tags: [Energy]
      summary: Renewable share
      parameters:
        - name: iso3
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /trade/health:
    get:
      tags: [Trade]
      summary: Service health
      security: []
      responses:
        '200':
          description: Success
  /trade/country/{iso3}:
    get:
      tags: [Trade]
      summary: Trade balance
      parameters:
        - name: iso3
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /trade/exports/{iso3}:
    get:
      tags: [Trade]
      summary: Export data
      parameters:
        - name: iso3
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /macro/api/v1/macro/health:
    get:
      tags: [Macro]
      summary: US economic health score
      responses:
        '200':
          description: Success
  /macro/api/v1/macro/gdp:
    get:
      tags: [Macro]
      summary: GDP data
      responses:
        '200':
          description: Success
  /macro/api/v1/macro/inflation:
    get:
      tags: [Macro]
      summary: Inflation data
      responses:
        '200':
          description: Success
  /macro/api/v1/macro/fed:
    get:
      tags: [Macro]
      summary: Fed rate data
      responses:
        '200':
          description: Success
  /memory/health:
    get:
      tags: [Memory]
      summary: Memory service status
      security: []
      responses:
        '200':
          description: Success
  /memory/snapshots:
    get:
      tags: [Memory]
      summary: Historical snapshots
      responses:
        '200':
          description: Success
  /memory/verify/{hash}:
    get:
      tags: [Memory]
      summary: Verify data delivery
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /api/nft/status:
    get:
      tags: [NFT]
      summary: Service status and contracts
      security: []
      responses:
        '200':
          description: Success
  /api/nft/contracts:
    get:
      tags: [NFT]
      summary: Contract addresses
      security: []
      responses:
        '200':
          description: Success
  /api/nft/tiers:
    get:
      tags: [NFT]
      summary: NFT tier definitions
      security: []
      responses:
        '200':
          description: Success
  /api/nft/gas:
    get:
      tags: [NFT]
      summary: Current gas prices
      security: []
      responses:
        '200':
          description: Success
  /api/nft/verify/{hash}:
    get:
      tags: [NFT]
      summary: Verify attestation receipt
      security: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
  /api/v2/attestation/status:
    get:
      tags: [DAP]
      summary: DAP service status
      responses:
        '200':
          description: Success
  /api/v2/attestation/chains:
    get:
      tags: [DAP]
      summary: Multi-chain anchoring status
      responses:
        '200':
          description: Success
  /api/v2/attestation/audit/export:
    get:
      tags: [DAP]
      summary: Export attestations for audit
      parameters:
        - name: start
          in: query
          schema:
            type: string
        - name: end
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
  /a2a/pricing:
    get:
      tags: [A2A]
      summary: View all feed prices
      security: []
      responses:
        '200':
          description: Success
  /a2a/balance:
    get:
      tags: [A2A]
      summary: Check USDC balance
      responses:
        '200':
          description: Success
  /a2a/usage:
    get:
      tags: [A2A]
      summary: Usage history
      responses:
        '200':
          description: Success
  /a2a/feed/{name}:
    get:
      tags: [A2A]
      summary: Get data after USDC payment
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: tx
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    StandardResponse:
      type: object
      properties:
        data:
          type: object
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        feed_name:
          type: string
        feed_version:
          type: string
        schema_version:
          type: string
          example: "1.0.0"
        as_of:
          type: string
          format: date-time
        data_sources:
          type: array
          items:
            type: string
        request_id:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
