openapi: 3.0.3
info:
  title: Essential Support API
  version: "1.0"
  description: |
    Essential Support API provides risk scoring and analysis for *essential blockchains* 
    (Polygon, GLMR, Arbitrum, Base, Polkadot, Solana, TON, BNB).

    All requests are routed through the unified `common` subdomain with a base path 
    `/essential-api-{essential_blockchain_ticker}`, where `essential_blockchain_ticker` 
    is used to select the blockchain network.

    These endpoints are optimized for high performance and return key risk metrics, including:
    - total transaction amounts
    - analysis depth
    - calculated risk scores (default, sensitive, and series-based)
    - detailed source and destination breakdowns

    The Essential Support API enables fast and lightweight risk evaluations without the full 
    complexity of deep blockchain analysis, making it ideal for quick compliance checks and monitoring.

servers:
  - url: https://common.glprotocol.com/essential-api-{essential_blockchain_ticker}
    variables:
      essential_blockchain_ticker:
        default: polygon
        enum:
          - polygon
          - glmr
          - arb
          - base
          - dot
          - sol
          - ton
          - bnb
        description: Essential blockchain ticker

paths:
  /report/tx_hash/{tx_hash}:
    get:
      tags:
        - Essential Support
      summary: Get Essential Transaction Risk Score
      description: >
        Retrieve detailed risk score for a transaction on essential blockchains.  
        Supports token-specific and directional analysis.
      parameters:
        - name: tx_hash
          in: path
          required: true
          description: Transaction hash to query
          schema:
            type: string
        - name: direction
          in: query
          required: false
          description: |
            Transaction search direction.  
            - `0` → Source of Funds (default)  
            - `1` → Use of Funds  
            - `2` → Common (Source + Use of Funds)
          schema:
            type: integer
            enum: [0, 1, 2]
        - name: token
          in: query
          required: false
          description: |
            Token contract address.  
            - empty → search by native coin  
            - contract address → search by specific token
          schema:
            type: string
        - name: x-api-key
          in: header
          required: true
          description: API key for authentication
          schema:
            type: string
      responses:
        "200":
          description: Successful risk report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EssentialRiskResponse"
              example:
                totalAmount: 18394532
                progress: 100
                depth: 2
                directTxCount: 2
                totalFunds: 50.95
                totalFundsDefault: 50
                totalFundsSensitive: 50
                totalFundsSeries: 50.95
                sources:
                  - directTx: "0xda85..."
                    directionUp: false
                    funds: { name: "DEX", score: 50 }
                    owner: "Uniswap"
                    depth: 2
                    amount: 9197266
                    currency: "0xc213..."
                    tx_hash: "0x755a..."
                    address: "0x9b08..."
                    timestamp: 1685019783
                    listType: "Known sources"
                    share: 1
        "401":
          description: Unauthorized
          content:
            application/json:
              example:
                response: "User not found"
                status: 401
                message: "User not found"
                name: "HttpException"
                code: 401
                success: false
                path: "/report/tx_hash/..."
                method: "GET"
                timestamp: "3/4/2025, 10:03:51 AM"
                data:
                  messageType: "error"
                  message: "User not found"
        "404":
          description: Transaction not found or hash not specified
          content:
            application/json:
              examples:
                notFound:
                  value:
                    messageType: "Error"
                    status: 404
                    code: 404
                    success: false
                    path: "/report/tx_hash/..."
                    method: "GET"
                    timestamp: "3/4/2025, 1:16:58 PM"
                    data:
                      messageType: "error"
                      message: "ENOENT"
                hashNotSpecified:
                  value:
                    response:
                      message: "Cannot GET /report/tx_hash/"
                      error: "Not Found"
                      statusCode: 404
                    status: 404
                    success: false
                    data:
                      messageType: "error"
                      message: "Cannot GET /report/tx_hash/"

  /report/address/{address}:
    get:
      tags:
        - Essential Support
      summary: Get Essential Address Risk Score
      description: >
        Retrieve risk score and last transaction details for an address on essential blockchains.
      parameters:
        - name: address
          in: path
          required: true
          description: Blockchain address to query
          schema:
            type: string
        - name: direction
          in: query
          required: false
          description: |
            Transaction search direction.  
            - `0` → Source of Funds (default)  
            - `1` → Use of Funds  
            - `2` → Common (Source + Use of Funds)
          schema:
            type: integer
            enum: [0, 1, 2]
        - name: token
          in: query
          required: false
          description: |
            Token contract address.  
            - empty → search by native coin  
            - contract address → search by specific token
          schema:
            type: string
        - name: x-api-key
          in: header
          required: true
          description: API key for authentication
          schema:
            type: string
      responses:
        "200":
          description: Successful risk report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EssentialRiskResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              example:
                response: "User not found"
                status: 401
                message: "User not found"
                name: "HttpException"
                code: 401
                success: false
                data:
                  messageType: "error"
                  message: "User not found"
        "404":
          description: Address not found or not specified
          content:
            application/json:
              examples:
                notFound:
                  value:
                    messageType: "Error"
                    status: 404
                    code: 404
                    success: false
                    path: "/report/address/..."
                    method: "GET"
                    timestamp: "3/4/2025, 1:16:58 PM"
                    data:
                      messageType: "error"
                      message: "ENOENT"
                addressNotSpecified:
                  value:
                    response:
                      message: "Cannot GET /report/address/"
                      error: "Not Found"
                      statusCode: 404
                    status: 404
                    success: false
                    data:
                      messageType: "error"
                      message: "Cannot GET /report/address/"

components:
  schemas:
    EssentialRiskResponse:
      type: object
      properties:
        totalAmount: { type: number }
        progress: { type: number }
        depth: { type: number }
        directTxCount: { type: number }
        totalFunds: { type: number }
        totalFundsDefault: { type: number }
        totalFundsSensitive: { type: number }
        totalFundsSeries: { type: number }
        sources:
          type: array
          items:
            type: object
            properties:
              directTx: { type: string }
              directionUp: { type: boolean }
              funds:
                type: object
                properties:
                  name: { type: string }
                  score: { type: number }
              owner: { type: string }
              depth: { type: number }
              amount: { type: number }
              currency: { type: string }
              tx_hash: { type: string }
              address: { type: string }
              directStamp: { type: number }
              timestamp: { type: number }
              listType: { type: string }
              share: { type: number }
