openapi: 3.1.0
info:
  title: Julie Autonomous EVM Security & Honeypot Scanner
  description: Real-time EVM smart contract security analysis, opcode disassembly, honeypot risk detection, and proxy implementation resolution for AI agents and Web3 applications.
  version: 2.1.0
servers:
  - url: https://juliesecuritynetwork.com
paths:
  /api/stream/pre-pair:
    get:
      operationId: ssePrePairStream
      summary: Real-time sub-millisecond pre-pair SSE security feed for snipers (3 free trial alerts, session key continuation)
      description: |
        Pushes verified opcode security verdicts for newly detected liquidity pool pairs on Base and Arbitrum Uniswap V3 at 0.15ms cache latency.
        Includes 3 free alerts per connection. After 3 alerts, returns an HTTP 402 payment_required event requiring an X-Session-Key header or ?session_key= parameter ($1.00 USDC Starter Pass for 125 scans or $5.00 USDC Pro Pass for 700 scans).
      parameters:
        - name: session_key
          in: query
          required: false
          description: Active session key from a $1.00 or $5.00 pass to bypass the 3-alert limit
          schema:
            type: string
            example: "sess_1729392000_abc123"
        - name: X-Session-Key
          in: header
          required: false
          description: Alternative header pass-through for persistent session authentication
          schema:
            type: string
            example: "sess_1729392000_abc123"
      responses:
        '200':
          description: SSE event stream (text/event-stream) streaming stream_connected, pre_pair_verdict, and payment_required events
          content:
            text/event-stream:
              schema:
                type: string
        '402':
          description: Stream quota reached - session key required for continuous feed
        '503':
          description: Connection capacity reached (max 30 concurrent streams)

  /api/batch/audit:
    post:
      operationId: batchAuditContracts
      summary: High-speed concurrent bytecode audit for up to 10 contracts via x402 ($0.05 Base USDC)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contracts
              properties:
                contracts:
                  type: array
                  items:
                    type: string
                    example: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
                  maxItems: 10
                  description: Array of up to 10 EVM smart contract addresses
                chain:
                  type: string
                  default: "base"
                  description: Target EVM blockchain (35 chains supported)
      responses:
        '200':
          description: Batch security evaluation results with binary safe_to_swap and kill_reason flags
        '402':
          description: Payment Required - Requires 0.05 Base Native USDC via EIP-712 Permit authorization

  /api/audit:
    get:
      operationId: auditPaidContract
      summary: Deep contract honeypot & reentrancy security audit via x402 protocol ($0.01 Base USDC)
      parameters:
        - name: contract
          in: query
          required: true
          description: The 0x EVM smart contract address to audit
          schema:
            type: string
            example: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        - name: chain
          in: query
          required: false
          description: Target EVM blockchain (default base)
          schema:
            type: string
            default: "base"
        - name: auto_pass
          in: query
          required: false
          description: Optional 1-click fallback session pass activation upon trial exhaustion (starter $1.00 for 125 credits, pro $5.00 for 750 credits)
          schema:
            type: string
            enum: ["starter", "pro", "institutional"]
      responses:
        '200':
          description: Official verified contract audit certificate and bytecode safety analysis
        '402':
          description: Payment Required - Requires 0.01 Base Native USDC via EIP-3009 authorization

  /api/scan:
    get:
      operationId: scanContractSecurity
      summary: Quick public audit of an EVM contract for honeypot traps and dangerous opcodes
      parameters:
        - name: contract
          in: query
          required: true
          description: The 0x EVM smart contract address to scan
          schema:
            type: string
            example: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        - name: chain
          in: query
          required: false
          description: Blockchain network (base, arbitrum, bsc, eth)
          schema:
            type: string
            default: "base"
            example: "base"
      responses:
        '200':
          description: Smart contract security report and honeypot risk score

  /api/proxy:
    get:
      operationId: resolveProxyImplementation
      summary: Resolve EIP-1967 transparent proxy implementation slots and ERC-1822 logic targets
      parameters:
        - name: contract
          in: query
          required: true
          description: EVM contract address
          schema:
            type: string
      responses:
        '200':
          description: Proxy detection and implementation contract address

  /api/metadata:
    get:
      operationId: getTokenMetadata
      summary: Fetch on-chain ERC-20 token metadata (Name, Symbol, Decimals, Total Supply)
      parameters:
        - name: contract
          in: query
          required: true
          description: ERC-20 contract address on Base
          schema:
            type: string
      responses:
        '200':
          description: Standard ERC-20 metadata details

  /api/signatures:
    get:
      operationId: scanHoneypotSignatures
      summary: Scan contract bytecode against known malicious function selectors and blacklist traps
      parameters:
        - name: contract
          in: query
          required: true
          description: Target contract address
          schema:
            type: string
      responses:
        '200':
          description: Recognized function signatures and blacklist warning flags

  /api/liquidity:
    get:
      operationId: checkLiquidityState
      summary: Analyze DEX liquidity status and LP verification on Base Mainnet
      parameters:
        - name: contract
          in: query
          required: true
          description: Token contract address
          schema:
            type: string
      responses:
        '200':
          description: Liquidity pool status and DEX verification details

  /api/feed:
    get:
      operationId: getHoneypotFeed
      summary: Real-time rolling feed of newly detected EVM smart contracts and threat scores
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Array of recently analyzed contracts across Base

  /api/metrics:
    get:
      operationId: getNetworkMetrics
      summary: Real-time verified network operations, unique global caller subnets, and sprint status
      responses:
        '200':
          description: Live network telemetry and multi-cloud traction metrics

  /api/status:
    get:
      operationId: getNetworkStatus
      summary: Network operational status, x402 pricing details, and settlement wallet coordinates
      responses:
        '200':
          description: Live network status report
