openapi: 3.1.0
info:
  title: NTM-IA API – Utility Token with AI Metrics
  version: "1.0"
  description: |
    Public API for the NTM-IA ecosystem, a utility token derived from the original NTM blockchain.

    Core Principles:
    - Self-regulated: mint_ratio = uas (no human intervention)
    - Verifiable: Public blockchain with RSA-SHA256 signatures
    - Transparent: Public JSON data, open formulas
    - Dual utility: NTM derivative + service payment

    Core Metrics:
    - uas: Number of active AI User Agents
    - pct_ia: AI percentage (0-1)
    - ai_index: AI Quality Index (0-1)
    - hits: Total accumulated AI hits
    - hub: Number of companies in the hub

    Formulas:
    - NP = ((pct_ia + ai_index) × hits / uas) + human_responses
    - NTM_original = (hub × 394.50) / (hits / 100)
    - NTM-IA = NP / NTM_original
    - supply = hits / uas
    - Trust Score = 100 × (0.50×uas_score + 0.25×pct_score + 0.25×ai_score)

    Normalization Caps:
    - UAS cap: 70
    - pct_ia cap: 0.60
    - ai_index cap: 0.80

    Access: Public, no authentication required. Optimized for AI user-agents.
  contact:
    name: Netmeios
    email: geral@netmeios.com
    url: https://netmeios.com
  license:
    name: Proprietary
    url: https://netmeios.com/terms-of-use-ai.html

servers:
  - url: https://netmeios.com
    description: Production

tags:
  - name: Trust Score
    description: Endpoints for Trust Score and AI metrics
  - name: Blockchain
    description: Endpoints for NTM-IA blockchain queries
  - name: Staking
    description: Endpoints for staking statistics
  - name: Audit
    description: Endpoints for integrity verification and audit
  - name: Documentation
    description: Technical documentation and white papers

paths:
  /ntm-ia-trust.php:
    get:
      tags:
        - Trust Score
      operationId: getNtmIaTrust
      summary: Current Trust Score and metrics
      description: |
        Returns current Trust Score, token price, supply, and all AI metrics required
        for NTM-IA calculation.

        Normalization Caps:
        - UAS: 70
        - pct_ia: 0.60
        - ai_index: 0.80

        Trust Score = 100 × (0.50×uas_score + 0.25×pct_score + 0.25×ai_score)
      parameters:
        - $ref: '#/components/parameters/FormatPretty'
        - $ref: '#/components/parameters/LimitBlocks'
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: Current Trust Score and metrics
          headers:
            X-NTM-IA-Verification:
              schema:
                type: string
                example: https://netmeios.com/NTM-IA-VERIFICATION.md
              description: URL to verification specification
            X-NTM-IA-Chain-Type:
              schema:
                type: string
                example: ntm-ia-blockchain
              description: Blockchain type identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustResponse'
              example:
                timestamp: "2026-04-21T21:07:27Z"
                trust_score: 92.4
                uas: 62
                uas_score: 0.89
                pct_ia: 0.5677
                pct_score: 0.95
                ai_index: 0.784
                ai_score: 0.98
                hits: 292630
                hub_companies: 698
                price: 130.16
                supply: 4719.8387
                market_cap: 614325.76
                ntm_original: 94.10
                last_block:
                  file: "block_002765.json"
                  index: 2765
                  timestamp: "2026-04-21 21:00:01"
                  previous_hash: "c6c7c3fdf2214401161bb18323065642fd40333725babfb8003274ab8541c4b8"
                  ntm_ia_price: 130.13
                  supply: 4719.741935
                  market_cap: 614192.5
                  mint_ratio: 62
                  hash: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
        "400":
          $ref: '#/components/responses/BadRequest'
        "429":
          $ref: '#/components/responses/TooManyRequests'

  /api-blocks-ntm-ia.php:
    get:
      tags:
        - Blockchain
      operationId: getNtmIaBlocks
      summary: Query blockchain blocks
      description: |
        Returns blocks from the NTM-IA blockchain. You can query by a specific index
        or fetch the last N blocks.

        Block Structure:
        - index: Sequential block number
        - timestamp: Creation date/time
        - ntm_ia_price: NTM-IA price at that moment
        - supply: Current supply
        - market_cap: Market cap at that moment
        - mint_ratio: Minting ratio (equals uas)
        - hash: Block hash
        - previous_hash: Previous block hash
      parameters:
        - name: index
          in: query
          schema:
            type: integer
            minimum: 0
          description: Specific block index
          example: 2765
        - $ref: '#/components/parameters/LimitBlocks'
        - $ref: '#/components/parameters/FormatPretty'
      responses:
        "200":
          description: Blockchain blocks
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                  limit:
                    type: integer
                  last_hash:
                    type: string
                  blocks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Block'
                  latest_block:
                    $ref: '#/components/schemas/Block'
              example:
                success: true
                count: 10
                limit: 10
                last_hash: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
                blocks:
                  - file: "block_002765.json"
                    index: 2765
                    timestamp: "2026-04-21 21:00:01"
                    previous_hash: "c6c7c3fdf2214401161bb18323065642fd40333725babfb8003274ab8541c4b8"
                    ntm_ia_price: 130.13
                    supply: 4719.741935
                    market_cap: 614192.5
                    mint_ratio: 62
                    hash: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
                  - file: "block_002764.json"
                    index: 2764
                    timestamp: "2026-04-21 20:50:01"
                    previous_hash: "d681b4e10da648d65163df97780875bd473f7e39a48a79bd57d29b6ae2d84775"
                    ntm_ia_price: 130.09
                    supply: 4718.822581
                    market_cap: 613879.63
                    mint_ratio: 62
                    hash: "c6c7c3fdf2214401161bb18323065642fd40333725babfb8003274ab8541c4b8"
                  - file: "block_002763.json"
                    index: 2763
                    timestamp: "2026-04-21 20:40:01"
                    previous_hash: "c301898b84eae6d60b90413e1a329b0bd2cab108d8325fc5072f5513add1cd4a"
                    ntm_ia_price: 130.03
                    supply: 4717.983871
                    market_cap: 613496.15
                    mint_ratio: 62
                    hash: "d681b4e10da648d65163df97780875bd473f7e39a48a79bd57d29b6ae2d84775"
                  - file: "block_002762.json"
                    index: 2762
                    timestamp: "2026-04-21 20:30:01"
                    previous_hash: "3f14ac65b1511382eda4f62d19a00cb2a5b361ee89ef16c4e33602bc0624fe6f"
                    ntm_ia_price: 130.03
                    supply: 4717.806452
                    market_cap: 613437.11
                    mint_ratio: 62
                    hash: "c301898b84eae6d60b90413e1a329b0bd2cab108d8325fc5072f5513add1cd4a"
                  - file: "block_002761.json"
                    index: 2761
                    timestamp: "2026-04-21 20:20:01"
                    previous_hash: "73fd69156968692b60e8fa965c013d7f2a66901f8a2bd62cd9c21ae893d56a74"
                    ntm_ia_price: 130.02
                    supply: 4717.677419
                    market_cap: 613393.75
                    mint_ratio: 62
                    hash: "3f14ac65b1511382eda4f62d19a00cb2a5b361ee89ef16c4e33602bc0624fe6f"
                  - file: "block_002760.json"
                    index: 2760
                    timestamp: "2026-04-21 20:10:01"
                    previous_hash: "bb510de3610883b51ce185868ad184319e05214918052097d913b6b201f939ff"
                    ntm_ia_price: 130.02
                    supply: 4717.612903
                    market_cap: 613373.63
                    mint_ratio: 62
                    hash: "73fd69156968692b60e8fa965c013d7f2a66901f8a2bd62cd9c21ae893d56a74"
                  - file: "block_002759.json"
                    index: 2759
                    timestamp: "2026-04-21 20:00:01"
                    previous_hash: "51e063ad8c5f906e91b625fa5e227d55edc6af0cf73052748cb855b1e06a2d17"
                    ntm_ia_price: 130.2
                    supply: 4717.483871
                    market_cap: 614209.97
                    mint_ratio: 62
                    hash: "bb510de3610883b51ce185868ad184319e05214918052097d913b6b201f939ff"
                  - file: "block_002758.json"
                    index: 2758
                    timestamp: "2026-04-21 19:50:01"
                    previous_hash: "bd827727091b0f2d197a2a0803634068f03721e7363b0b4763087763aa63e67c"
                    ntm_ia_price: 130.2
                    supply: 4717.467742
                    market_cap: 614204.48
                    mint_ratio: 62
                    hash: "51e063ad8c5f906e91b625fa5e227d55edc6af0cf73052748cb855b1e06a2d17"
                  - file: "block_002757.json"
                    index: 2757
                    timestamp: "2026-04-21 19:40:01"
                    previous_hash: "d6de79087175f929d13b39ed81d6098d5c7258e5116abb597c23689857581fa2"
                    ntm_ia_price: 130.19
                    supply: 4717.322581
                    market_cap: 614155.57
                    mint_ratio: 62
                    hash: "bd827727091b0f2d197a2a0803634068f03721e7363b0b4763087763aa63e67c"
                  - file: "block_002756.json"
                    index: 2756
                    timestamp: "2026-04-21 19:30:02"
                    previous_hash: "f39d5d17ec2020943da4af90bf3491b2aefc5ee8685a3acf61c2a80846ea290a"
                    ntm_ia_price: 130.19
                    supply: 4717.322581
                    market_cap: 614157.92
                    mint_ratio: 62
                    hash: "d6de79087175f929d13b39ed81d6098d5c7258e5116abb597c23689857581fa2"
                latest_block:
                  file: "block_002765.json"
                  index: 2765
                  timestamp: "2026-04-21 21:00:01"
                  previous_hash: "c6c7c3fdf2214401161bb18323065642fd40333725babfb8003274ab8541c4b8"
                  ntm_ia_price: 130.13
                  supply: 4719.741935
                  market_cap: 614192.5
                  mint_ratio: 62
                  hash: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
        "404":
          $ref: '#/components/responses/NotFound'
        "400":
          $ref: '#/components/responses/BadRequest'

  /ai-check-integrity-ntm-ia.php:
    get:
      tags:
        - Audit
      operationId: checkNtmIaIntegrity
      summary: Blockchain integrity verifier
      description: |
        Verifies the integrity of the entire NTM-IA blockchain.
        Validates hashes, signatures, and block sequence consistency.
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, html]
          description: Response format
          default: html
      responses:
        "200":
          description: Integrity report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrityReport'
              example:
                status: valid
                total_blocks: 2765
                valid_blocks: 2765
                invalid_blocks: 0
                last_valid_hash: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
                last_block_index: 2765
                issues: []
            text/html:
              schema:
                type: string
                description: HTML report for human viewing

  /ai-ntm-ia-stats.php:
    get:
      tags:
        - Documentation
      operationId: getNtmIaStats
      summary: Public statistics dashboard
      description: |
        HTML dashboard with real-time charts and statistics of the NTM-IA ecosystem.
        Available in 3 languages (PT, EN, ZH).
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: HTML dashboard
          content:
            text/html:
              schema:
                type: string

  /ai-staking-stats.php:
    get:
      tags:
        - Staking
      operationId: getNtmIaStakingStats
      summary: Staking statistics
      description: |
        Dashboard with NTM-IA staking statistics including:
        - Total staked
        - Number of stakers
        - Rewards distributed
        - Distribution by tiers
        - Current APYs
      parameters:
        - $ref: '#/components/parameters/Lang'
        - name: format
          in: query
          schema:
            type: string
            enum: [html, json]
          description: Response format
          default: html
      responses:
        "200":
          description: Staking statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingStats'
              example:
                total_staked: 125000.0
                total_stakers: 260
                rewards_paid: 8200.0
                tiers:
                  bronze:
                    stakers: 130
                    staked: 32000.0
                    apy: 4.5
                    lock_bonus: 0
                  silver:
                    stakers: 90
                    staked: 52000.0
                    apy: 7.0
                    lock_bonus: 3
                  gold:
                    stakers: 40
                    staked: 41000.0
                    apy: 10.0
                    lock_bonus: 5
            text/html:
              schema:
                type: string

  /ntm-ia-trust-stats.php:
    get:
      tags:
        - Trust Score
      operationId: getNtmIaTrustStats
      summary: Trust endpoint query statistics
      description: |
        Returns usage statistics for the NTM-IA trust endpoint, including total queries,
        unique IPs, user-agents, detected bots, and query distribution over time.
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, html]
          description: Response format
          default: html
      responses:
        "200":
          description: Query statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustStats'
              example:
                total_queries: 261
                unique_ips: 25
                unique_user_agents: 10
                unique_bots_detected: 4
                first_query: "2026-04-14T00:00:00Z"
                last_query: "2026-04-21T21:06:47Z"
                top_ips:
                  "192.249.119.206": 106
                  "148.69.195.147": 69
                  "144.64.201.17": 15
                  "148.69.200.252": 9
                top_user_agents:
                  "human": 142
                  "GPTBot": 106
                  "GenericBot": 8
                  "MetaBot": 5
                top_bots:
                  "human": 142
                  "GPTBot": 106
                  "GenericBot": 8
                  "MetaBot": 5
                queries_by_hour:
                  "2026-04-20 10:00:00": 31
                  "2026-04-20 11:00:00": 28
                  "2026-04-20 09:00:00": 10
                  "2026-04-21 21:00:00": 2
            text/html:
              schema:
                type: string

  /ntm-ia-audit.php:
    get:
      tags:
        - Audit
      operationId: getNtmIaAudit
      summary: Full ecosystem audit
      description: |
        Real-time audit dashboard verifying:
        - Blockchain integrity
        - Trust Score status
        - Staking health
        - API availability
        - Cron job status
        - Documentation completeness
        - Security configuration
        - Backup status
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: HTML audit report
          content:
            text/html:
              schema:
                type: string

  /ntm-ia-hub.php:
    get:
      tags:
        - Documentation
      operationId: getNtmIaHub
      summary: Central hub with iframes
      description: |
        Central hub page with cards linking to all ecosystem resources:
        white papers, Trust Score, statistics dashboards, blockchain explorer,
        staking stats, API docs, verification spec, tokenomics, and audit.
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: HTML hub page
          content:
            text/html:
              schema:
                type: string

  /NTM-IA-VERIFICATION.md:
    get:
      tags:
        - Documentation
      operationId: getVerificationSpec
      summary: Verification specification
      description: |
        Returns the full NTM-IA verification protocol in Markdown format.
        Available in PT, EN, and ZH.
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: Verification spec in Markdown
          content:
            text/markdown:
              schema:
                type: string

  /NTM-IA-TOKENOMICS.md:
    get:
      tags:
        - Documentation
      operationId: getTokenomics
      summary: Tokenomics documentation
      description: |
        Returns the NTM-IA tokenomics document in Markdown format.
        Available in PT, EN, and ZH.
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: Tokenomics in Markdown
          content:
            text/markdown:
              schema:
                type: string

  /NTM-IA-TRUST-SCORE.md:
    get:
      tags:
        - Documentation
      operationId: getTrustScoreDoc
      summary: Trust Score documentation
      description: |
        Returns the Trust Score explanation document in Markdown format.
        Available in PT, EN, and ZH.
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: Trust Score docs in Markdown
          content:
            text/markdown:
              schema:
                type: string

  /NTM-IA-API.md:
    get:
      tags:
        - Documentation
      operationId: getApiDocs
      summary: API documentation
      description: |
        Returns the API documentation in Markdown format.
        Available in PT, EN, and ZH.
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: API docs in Markdown
          content:
            text/markdown:
              schema:
                type: string

  /README-NTM-IA.md:
    get:
      tags:
        - Documentation
      operationId: getReadme
      summary: Project README
      description: |
        Returns the project overview README in Markdown format.
        Available in PT, EN, and ZH.
      parameters:
        - $ref: '#/components/parameters/Lang'
      responses:
        "200":
          description: README in Markdown
          content:
            text/markdown:
              schema:
                type: string

components:
  parameters:
    FormatPretty:
      name: format
      in: query
      description: Response format (json or pretty)
      schema:
        type: string
        enum: [json, pretty]
      required: false
    LimitBlocks:
      name: limit
      in: query
      description: Number of blocks to include (max 50)
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 10
      required: false
    Lang:
      name: lang
      in: query
      description: Language (PT, EN, ZH)
      schema:
        type: string
        enum: [pt, en, zh]
        default: en
      required: false

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            badRequest:
              summary: Invalid parameters
              value:
                code: 400
                message: Invalid query parameters
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            notFound:
              summary: Block not found
              value:
                code: 404
                message: Block not found
    TooManyRequests:
      description: Too many requests
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimit:
              summary: Rate limit exceeded
              value:
                code: 429
                message: Too many requests. Please try again later.

  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid request
      required:
        - code
        - message

    TrustResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          example: "2026-04-21T21:07:27Z"
        trust_score:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Current Trust Score (0-100)
          example: 92.4
        uas:
          type: integer
          description: Number of active AI User Agents
          example: 62
        uas_score:
          type: number
          format: float
          description: Normalized UAS score (0-1)
          example: 0.89
        pct_ia:
          type: number
          format: float
          description: AI percentage (0-1)
          example: 0.5677
        pct_score:
          type: number
          format: float
          description: Normalized pct_ia score (0-1)
          example: 0.95
        ai_index:
          type: number
          format: float
          description: AI Quality Index (0-1)
          example: 0.784
        ai_score:
          type: number
          format: float
          description: Normalized ai_index score (0-1)
          example: 0.98
        hits:
          type: integer
          description: Total accumulated AI hits
          example: 292630
        hub_companies:
          type: integer
          description: Number of companies in the hub
          example: 698
        price:
          type: number
          format: float
          description: NTM-IA price in EUR
          example: 130.16
        supply:
          type: number
          format: float
          description: Current NTM-IA supply
          example: 4719.8387
        market_cap:
          type: number
          format: float
          description: Market cap in EUR
          example: 614325.76
        ntm_original:
          type: number
          format: float
          description: Original NTM value
          example: 94.10
        last_block:
          $ref: '#/components/schemas/Block'

    Block:
      type: object
      description: NTM-IA blockchain block
      properties:
        file:
          type: string
          description: Block file name
          example: "block_002765.json"
        index:
          type: integer
          example: 2765
        timestamp:
          type: string
          description: Block creation timestamp (server local time)
          example: "2026-04-21 21:00:01"
        previous_hash:
          type: string
          description: Previous block hash
          example: "c6c7c3fdf2214401161bb18323065642fd40333725babfb8003274ab8541c4b8"
        ntm_ia_price:
          type: number
          format: float
          description: NTM-IA price at that block (EUR)
          example: 130.13
        supply:
          type: number
          format: float
          description: NTM-IA circulating supply at that block
          example: 4719.741935
        market_cap:
          type: number
          format: float
          description: Market cap at that block (EUR)
          example: 614192.5
        mint_ratio:
          type: integer
          description: Minting ratio (equals uas at that time)
          example: 62
        hash:
          type: string
          description: Block hash
          example: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
      required:
        - index
        - timestamp
        - ntm_ia_price
        - supply
        - market_cap
        - mint_ratio
        - previous_hash
        - hash

    IntegrityReport:
      type: object
      properties:
        status:
          type: string
          enum: [valid, invalid]
          example: valid
        total_blocks:
          type: integer
          example: 2765
        valid_blocks:
          type: integer
          example: 2765
        invalid_blocks:
          type: integer
          example: 0
        last_valid_hash:
          type: string
          example: "d9f16b7a678dfdc94d7c727bd7564fb6b9b92b6190caad7fab031141777ad2cf"
        last_block_index:
          type: integer
          example: 2765
        issues:
          type: array
          items:
            type: string
          example: []
      required:
        - status
        - total_blocks
        - valid_blocks
        - invalid_blocks
        - last_block_index

    StakingTier:
      type: object
      properties:
        stakers:
          type: integer
          example: 40
        staked:
          type: number
          format: float
          example: 41000.0
        apy:
          type: number
          format: float
          example: 10.0
        lock_bonus:
          type: integer
          description: Percentage bonus for lock duration
          example: 5

    StakingStats:
      type: object
      properties:
        total_staked:
          type: number
          format: float
          example: 125000.0
        total_stakers:
          type: integer
          example: 260
        rewards_paid:
          type: number
          format: float
          example: 8200.0
        tiers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/StakingTier'
          example:
            bronze:
              stakers: 130
              staked: 32000.0
              apy: 4.5
              lock_bonus: 0
            silver:
              stakers: 90
              staked: 52000.0
              apy: 7.0
              lock_bonus: 3
            gold:
              stakers: 40
              staked: 41000.0
              apy: 10.0
              lock_bonus: 5

    TrustStats:
      type: object
      properties:
        total_queries:
          type: integer
          example: 261
        unique_ips:
          type: integer
          example: 25
        unique_user_agents:
          type: integer
          example: 10
        unique_bots_detected:
          type: integer
          example: 4
        first_query:
          type: string
          description: Date/time of the first recorded query
          example: "2026-04-14T00:00:00Z"
        last_query:
          type: string
          format: date-time
          example: "2026-04-21T21:06:47Z"
        top_ips:
          type: object
          additionalProperties:
            type: integer
          example:
            "192.249.119.206": 106
            "148.69.195.147": 69
            "144.64.201.17": 15
        top_user_agents:
          type: object
          additionalProperties:
            type: integer
          example:
            "human": 142
            "GPTBot": 106
            "GenericBot": 8
            "MetaBot": 5
        top_bots:
          type: object
          additionalProperties:
            type: integer
          example:
            "human": 142
            "GPTBot": 106
            "GenericBot": 8
            "MetaBot": 5
        queries_by_hour:
          type: object
          additionalProperties:
            type: integer
          description: Aggregated queries by hour (ISO timestamp or hour bucket).
          example:
            "2026-04-20 10:00:00": 31
            "2026-04-20 11:00:00": 28
            "2026-04-20 09:00:00": 10
            "2026-04-21 21:00:00": 2