openapi: 3.2.0
info:
  title: Qorevia Market Intelligence Utility API
  version: 2.0.0
  description: Agent-payable market intelligence, data profiling and deterministic utility tools.
  x-guidance: Use these tools for market/session/risk/backtest context and local data profiling. Paid routes use HTTP 402/x402 and settle USDC directly to the provider wallet.
servers:
- url: https://api.flowhomes.eu
tags:
- name: Utility
paths:
  /api/jwt-decode:
    post:
      summary: Decode JWT header and payload without signature verification
      operationId: jwt_decode
      tags:
      - Utility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
              required:
              - token
            example:
              token: eyJhbGciOiJub25lIn0.eyJzdWIiOiIxMjMifQ.
      responses:
        '200':
          description: Paid response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                header:
                  alg: none
                payload:
                  sub: '123'
                verified: false
        '402':
          description: x402 payment required
        '503':
          description: Upstream market-data source unavailable; payment is not requested for MT5 routes during preflight failure.
      x-payment-info:
        price: '0.002500'
        currency: USDC
        network: eip155:8453
        protocol: x402
  /api/tick-pnl:
    post:
      summary: Calculate PnL from entry exit contracts tick size and tick value
      operationId: tick_pnl
      tags:
      - Utility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entry:
                  type: number
                exit:
                  type: number
                contracts:
                  type: number
                tickSize:
                  type: number
                tickValue:
                  type: number
                direction:
                  type: string
                  enum:
                  - long
                  - short
              required:
              - entry
              - exit
              - contracts
              - tickSize
              - tickValue
              - direction
            example:
              entry: 100
              exit: 101
              contracts: 2
              tickSize: 0.25
              tickValue: 12.5
              direction: long
      responses:
        '200':
          description: Paid response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                ticks: 4
                pnl: 100
        '402':
          description: x402 payment required
        '503':
          description: Upstream market-data source unavailable; payment is not requested for MT5 routes during preflight failure.
      x-payment-info:
        price: '0.050000'
        currency: USDC
        network: eip155:8453
        protocol: x402
  /api/evm-address-syntax:
    post:
      summary: Validate basic EVM 20-byte hex address syntax
      operationId: evm_address_syntax
      tags:
      - Utility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
              required:
              - address
            example:
              address: '0x0000000000000000000000000000000000000000'
      responses:
        '200':
          description: Paid response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                valid: true
        '402':
          description: x402 payment required
        '503':
          description: Upstream market-data source unavailable; payment is not requested for MT5 routes during preflight failure.
      x-payment-info:
        price: '0.010000'
        currency: USDC
        network: eip155:8453
        protocol: x402
  /api/ohlcv-state:
    post:
      summary: Compute simple return range position and true-range average from supplied OHLCV…
      operationId: ohlcv_state
      tags:
      - Utility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                bars:
                  type: array
              required:
              - bars
            example:
              bars:
              - open: 100
                high: 102
                low: 99
                close: 101
              - open: 101
                high: 103
                low: 100
                close: 102
      responses:
        '200':
          description: Paid response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                returnPct: 1
                rangePosition: 0.75
                atr: 3
        '402':
          description: x402 payment required
        '503':
          description: Upstream market-data source unavailable; payment is not requested for MT5 routes during preflight failure.
      x-payment-info:
        price: '0.002500'
        currency: USDC
        network: eip155:8453
        protocol: x402
  /api/regex-test:
    post:
      summary: Run a supplied JavaScript regular expression against supplied text
      operationId: regex_test
      tags:
      - Utility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pattern:
                  type: string
                flags:
                  type: string
                text:
                  type: string
              required:
              - pattern
              - text
            example:
              pattern: \d+
              flags: g
              text: a12b34
      responses:
        '200':
          description: Paid response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                matched: true
                matches:
                - '12'
                - '34'
        '402':
          description: x402 payment required
        '503':
          description: Upstream market-data source unavailable; payment is not requested for MT5 routes during preflight failure.
      x-payment-info:
        price: '0.003400'
        currency: USDC
        network: eip155:8453
        protocol: x402