openapi: 3.0.0
info:
  title: SolaceScanScout API
  version: 1.0.0
  description: |
    SolaceScanScout - The Defi Oracle Meta Explorer API
    
    Comprehensive blockchain explorer API for ChainID 138 with cross-chain bridge monitoring,
    WETH utilities, and real-time transaction tracking.
  contact:
    name: SolaceScanScout Support
    url: https://explorer.d-bis.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://explorer.d-bis.org/api
    description: Production server
  - url: http://localhost:8080/api
    description: Local development server

tags:
  - name: Blocks
    description: Block information and queries
  - name: Transactions
    description: Transaction information and queries
  - name: Addresses
    description: Address information and balances
  - name: Search
    description: Unified search across blocks, transactions, and addresses
  - name: Health
    description: Health check and status endpoints

paths:
  /v1/blocks:
    get:
      tags:
        - Blocks
      summary: List blocks
      description: Get a paginated list of blocks
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: List of blocks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Block'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'

  /v1/blocks/{chain_id}/{number}:
    get:
      tags:
        - Blocks
      summary: Get block by number
      parameters:
        - name: chain_id
          in: path
          required: true
          schema:
            type: integer
            example: 138
        - name: number
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Block details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Block'
        '404':
          description: Block not found
        '400':
          description: Invalid request

  /v1/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
        - name: block_number
          in: query
          schema:
            type: integer
        - name: from_address
          in: query
          schema:
            type: string
        - name: to_address
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of transactions

  /v1/transactions/{chain_id}/{hash}:
    get:
      tags:
        - Transactions
      summary: Get transaction by hash
      parameters:
        - name: chain_id
          in: path
          required: true
          schema:
            type: integer
        - name: hash
          in: path
          required: true
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{64}$'
      responses:
        '200':
          description: Transaction details
        '404':
          description: Transaction not found

  /v1/addresses/{chain_id}/{address}:
    get:
      tags:
        - Addresses
      summary: Get address information
      parameters:
        - name: chain_id
          in: path
          required: true
          schema:
            type: integer
        - name: address
          in: path
          required: true
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
      responses:
        '200':
          description: Address information

  /v1/search:
    get:
      tags:
        - Search
      summary: Unified search
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Search results

  /health:
    get:
      tags:
        - Health
      summary: Health check
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'

components:
  schemas:
    Block:
      type: object
      properties:
        chain_id:
          type: integer
        number:
          type: integer
        hash:
          type: string
        parent_hash:
          type: string
        timestamp:
          type: string
          format: date-time
        miner:
          type: string
        transaction_count:
          type: integer
        gas_used:
          type: integer
        gas_limit:
          type: integer
        size:
          type: integer

    Transaction:
      type: object
      properties:
        chain_id:
          type: integer
        hash:
          type: string
        block_number:
          type: integer
        from_address:
          type: string
        to_address:
          type: string
        value:
          type: string
        gas_price:
          type: integer
        gas_used:
          type: integer
        status:
          type: integer

    Address:
      type: object
      properties:
        address:
          type: string
        chain_id:
          type: integer
        balance:
          type: string
        transaction_count:
          type: integer
        token_count:
          type: integer
        is_contract:
          type: boolean

    PaginationMeta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            page:
              type: integer
            page_size:
              type: integer

    HealthStatus:
      type: object
      properties:
        status:
          type: string
        timestamp:
          type: string
        services:
          type: object
        chain_id:
          type: integer
        explorer:
          type: object
          properties:
            name:
              type: string
            version:
              type: string

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []