openapi: 3.0.1
info:
  title: Vibe Springs API
  description: 'Pay-per-use AI utilities: image conversion, PDF generation, CSV processing, and historical weather data. All endpoints require x402 USDC payments on Base mainnet. No API keys needed.'
  version: v2
  contact:
    name: Vibe Springs Support
    email: support@vibesprings.net
    url: https://vibesprings.net/for-agents
  x-guidance: 'Vibe Springs: 50 pay-per-use AI endpoints for autonomous agents via x402 micropayments on Base. Categories: (1) Weather & Environmental Intelligence — historical weather, forecasts, air quality, marine, earthquakes, floods, solar/UV, and weather-driven delay-risk. (2) Finance — forex rates, currency conversion, rate history, crypto prices, market data, public holidays. (3) Blockchain & On-chain — gas fees, wallet profiling, DeFi yield scanning, price oracles (BTC, ETH, SOL, Base gas), address risk scoring. (4) Mock Social Intelligence — deterministic synthetic social feeds and scenario streams for agent testing, not live social data. (5) Processing Tools — PDF generation, image conversion, CSV cleaning, email alerts. (6) Composite Intelligence — market-pulse (crypto+FX+gas+DeFi), travel-brief (forecast+air+holidays+FX), portfolio-brief (wallet+risk+yields+gas), risk-report (6-signal due diligence). (7) Workflows — location-report, invoice-fx, csv-to-pdf. (8) Agent Infrastructure — wallet status checker, API health scanner, service discovery proxy, API AEO visibility auditor. (9) x402 Market Intelligence — listing authenticity and health audits, category trends, competitor analysis, and a historical archive of the Bazaar itself that the Coinbase discovery API does not retain. Pricing: $0.001-$25.00 USDC per call. No API keys or accounts needed — just x402 wallet signatures on Base mainnet (eip155:8453).'
servers:
  - url: https://vibesprings.net
paths:
  /api/convert-image:
    post:
      operationId: convertImage
      summary: Convert, resize, and optimize images. Supports JPG, PNG, WebP, AVIF.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Image file (max 10MB)
                format:
                  type: string
                  enum:
                    - webp
                    - jpg
                    - png
                    - avif
                  default: webp
                width:
                  type: integer
                  description: Resize width in pixels
                height:
                  type: integer
                  description: Resize height in pixels
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 80
                preset:
                  type: string
                  enum:
                    - nft-ready
                    - web-optimized
      responses:
        '200':
          description: Converted image binary
          content:
            image/*:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid input
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.05'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/generate-pdf:
    post:
      operationId: generatePdf
      summary: Generate professional PDFs from structured JSON data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template:
                  type: string
                  enum:
                    - invoice
                    - resume
                    - report
                    - contract
                    - receipt
                    - document
                  default: document
                data:
                  type: object
                  description: Template-specific data
                options:
                  type: object
                  properties:
                    pageSize:
                      type: string
                      enum:
                        - A4
                        - Letter
                    watermark:
                      type: string
      responses:
        '200':
          description: PDF binary
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.10'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/process-csv:
    post:
      operationId: processCsv
      summary: Clean, filter, and analyze CSV files. Output as JSON, CSV, or PDF summary.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file (max 10MB)
                instructions:
                  type: string
                  description: JSON string with processing instructions
      responses:
        '200':
          description: Processed data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.03'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/weather:
    get:
      operationId: getHistoricalWeather
      summary: Get historical weather data for any location and date range.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
          description: City name or location
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date (YYYY-MM-DD, must be in the past)
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date (YYYY-MM-DD, must be yesterday or earlier)
      responses:
        '200':
          description: Historical weather data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/forecast:
    get:
      operationId: getForecast
      summary: Up to 16-day weather forecast for any location.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Forecast data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/delay-risk:
    get:
      operationId: getDelayRisk
      summary: Weather-driven scheduling-disruption risk score for US locations.
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
        - name: lon
          in: query
          required: true
          schema:
            type: number
        - name: profile
          in: query
          required: false
          schema:
            type: string
            enum:
              - ground_work
              - outdoor_event
              - logistics
              - aerial
        - name: days
          in: query
          required: false
          schema:
            type: integer
        - name: soil
          in: query
          required: false
          schema:
            type: string
        - name: hydrologicGroup
          in: query
          required: false
          schema:
            type: string
        - name: drainageClass
          in: query
          required: false
          schema:
            type: string
        - name: gradient
          in: query
          required: false
          schema:
            type: string
            enum:
              - flat
              - moderate
              - steep
        - name: exposure
          in: query
          required: false
          schema:
            type: string
            enum:
              - open
              - shaded
      responses:
        '200':
          description: Delay risk analysis
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input or outside US coverage (OUT_OF_COVERAGE)
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.25'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/demo/delay-risk:
    get:
      operationId: getDelayRiskDemo
      summary: 'Demo: weather-driven delay-risk score for 5 fixed US locations.'
      parameters:
        - name: location
          in: query
          required: false
          schema:
            type: string
            enum:
              - nova
              - houston
              - seattle
              - denver
              - miami
        - name: profile
          in: query
          required: false
          schema:
            type: string
            enum:
              - ground_work
              - outdoor_event
              - logistics
              - aerial
        - name: soil
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Demo delay risk analysis
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/air-quality:
    get:
      operationId: getAirQuality
      summary: Current and forecast air quality for any location.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Air quality data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/marine:
    get:
      operationId: getMarineWeather
      summary: Marine and ocean conditions for coastal locations.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Marine weather data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/earthquakes:
    get:
      operationId: getEarthquakes
      summary: Recent earthquakes near a location.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Earthquake data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/flood:
    get:
      operationId: getFlood
      summary: Flood risk and river discharge data.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Flood data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/solar:
    get:
      operationId: getSolar
      summary: Solar radiation and energy forecast.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Solar data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/exchange:
    get:
      operationId: getExchangeRates
      summary: Real-time and historical fiat exchange rates.
      parameters:
        - name: base
          in: query
          required: false
          schema:
            type: string
        - name: target
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Exchange rate data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/holidays:
    get:
      operationId: getHolidays
      summary: Public holidays for any country.
      parameters:
        - name: country
          in: query
          required: true
          schema:
            type: string
        - name: year
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Holiday data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/exchange/convert:
    get:
      operationId: convertCurrency
      summary: Convert an amount between any two fiat currencies with live ECB rates.
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
          description: Source currency ISO code (e.g. GBP, USD)
        - name: to
          in: query
          required: true
          schema:
            type: string
          description: Target currency ISO code (e.g. JPY, EUR)
        - name: amount
          in: query
          required: false
          schema:
            type: string
          description: Amount to convert (default 1)
      responses:
        '200':
          description: Conversion result with rate and inverse rate
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/exchange/history:
    get:
      operationId: getExchangeHistory
      summary: Daily exchange rate time series for any currency pair, up to 365 days.
      parameters:
        - name: base
          in: query
          required: false
          schema:
            type: string
          description: Base currency ISO code (default USD)
        - name: to
          in: query
          required: false
          schema:
            type: string
          description: Target currency ISO code (default EUR)
        - name: start
          in: query
          required: true
          schema:
            type: string
          description: Start date YYYY-MM-DD
        - name: end
          in: query
          required: true
          schema:
            type: string
          description: End date YYYY-MM-DD
      responses:
        '200':
          description: Time series data with summary statistics
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/crypto:
    get:
      operationId: getCryptoPrices
      summary: Live cryptocurrency prices, market caps, volume, and changes for top tokens.
      parameters:
        - name: ids
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated CoinGecko IDs (e.g. bitcoin,ethereum). Omit for top coins.
        - name: vs
          in: query
          required: false
          schema:
            type: string
          description: Quote currency (usd, eur, gbp, jpy, btc, eth). Default usd.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Max results 1-100 (default 25)
      responses:
        '200':
          description: Cryptocurrency market data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/workflow/invoice-fx:
    post:
      operationId: generateInvoiceFX
      summary: Multi-currency invoice workflow. Converts line items to target currency and generates PDF.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - to
                - targetCurrency
                - items
              properties:
                invoiceNumber:
                  type: string
                from:
                  type: object
                  properties:
                    name:
                      type: string
                    address:
                      type: string
                    email:
                      type: string
                to:
                  type: object
                  properties:
                    name:
                      type: string
                    address:
                      type: string
                    email:
                      type: string
                targetCurrency:
                  type: string
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      description:
                        type: string
                      quantity:
                        type: number
                      unitPrice:
                        type: number
                      currency:
                        type: string
                notes:
                  type: string
                dueDate:
                  type: string
      responses:
        '200':
          description: Generated PDF invoice
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.15'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/alert:
    post:
      operationId: sendAlert
      summary: Dispatch secure, PII-scrubbed email alerts to human operators.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  description: The recipient email address.
                  format: email
                subject:
                  type: string
                  description: The subject of the alert email (maximum 120 characters).
                  maxLength: 120
                body:
                  type: string
                  description: The body of the notification (maximum 2000 characters).
                  maxLength: 2000
              required:
                - to
                - subject
                - body
      responses:
        '200':
          description: Alert successfully scrubbed and sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  recipient:
                    type: string
                  processingTime:
                    type: string
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/market-data:
    get:
      operationId: getMarketData
      summary: Unified real-time stock and crypto market price feed.
      parameters:
        - name: symbols
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Standardized price data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/address-risk:
    get:
      operationId: getAddressRisk
      summary: On-chain address risk scoring and intelligence.
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          description: Ethereum address (0x-prefixed, 42 characters) to analyze.
        - name: network
          in: query
          required: false
          schema:
            type: string
            enum:
              - ethereum
              - base
              - base-sepolia
            default: ethereum
          description: 'Target network to query (default: ethereum)'
      responses:
        '200':
          description: Risk score and intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.03'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/wallet-intel:
    get:
      operationId: getWalletIntel
      summary: Comprehensive wallet intelligence and profiling.
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          description: The Ethereum address to profile (0x-prefixed, 42 characters). Supports EOAs and smart contracts.
        - name: chain
          in: query
          required: false
          schema:
            type: string
            default: base
          description: 'Target chain: ethereum, base, or sepolia (default: base)'
      responses:
        '200':
          description: Wallet profile and token balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletIntelResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.10'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/defi-yields:
    get:
      operationId: getDefiYields
      summary: Aggregated DeFi yield scanner powered by DefiLlama.
      parameters:
        - name: token
          in: query
          required: false
          schema:
            type: string
            default: USDC
          description: 'Token symbol to filter by (e.g. ''USDC'', ''ETH'', ''WBTC''). Default: ''USDC''.'
        - name: chain
          in: query
          required: false
          schema:
            type: string
          description: Chain to filter by (e.g. 'base', 'ethereum', 'arbitrum', 'optimism'). Omit for all chains.
        - name: min_tvl
          in: query
          required: false
          schema:
            type: string
            default: '100000'
          description: 'Minimum TVL in USD (e.g. ''100000''). Default: 100000.'
        - name: limit
          in: query
          required: false
          schema:
            type: string
            default: '20'
          description: 'Max results to return (1-50). Default: 20.'
        - name: sort
          in: query
          required: false
          schema:
            type: string
            default: apy
          description: 'Sort by: ''apy'', ''tvl'', or ''protocol''. Default: ''apy''.'
      responses:
        '200':
          description: List of yield opportunities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefiYieldsResponse'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.06'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/gas:
    get:
      operationId: getGasPrice
      summary: Real-time gas price oracle for multiple EVM chains.
      parameters:
        - name: chain
          in: query
          required: false
          schema:
            type: string
            default: base
          description: 'Network to query gas prices for. Options: base, ethereum, arbitrum, optimism. Default: base.'
      responses:
        '200':
          description: Gas price estimate and transaction cost estimates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasOracleResponse'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/market-pulse:
    get:
      operationId: getMarketPulse
      summary: Real-time market snapshot (crypto, forex, DeFi yields, gas).
      parameters:
        - name: cryptos
          in: query
          required: false
          schema:
            type: string
            default: bitcoin,ethereum,solana
          description: Comma-separated CoinGecko token IDs.
        - name: base
          in: query
          required: false
          schema:
            type: string
            default: USD
          description: Base fiat currency for FX rates.
      responses:
        '200':
          description: Market snapshot data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.05'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/travel-brief:
    get:
      operationId: getTravelBrief
      summary: Destination intelligence (forecast, air quality, holidays, FX).
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
          description: City or place name.
        - name: country
          in: query
          required: false
          schema:
            type: string
          description: ISO-3166-1 alpha-2 country code override.
        - name: currency
          in: query
          required: false
          schema:
            type: string
            default: USD
          description: Target currency for FX rates.
      responses:
        '200':
          description: Travel brief data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.05'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/portfolio-brief:
    get:
      operationId: getPortfolioBrief
      summary: DeFi portfolio snapshot (balance, tokens, risk, yields, gas).
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          description: Ethereum wallet address to profile.
        - name: chain
          in: query
          required: false
          schema:
            type: string
            default: base
          description: 'Target chain: base, ethereum, or sepolia.'
      responses:
        '200':
          description: Portfolio snapshot data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.10'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/risk-report:
    get:
      operationId: getRiskReport
      summary: On-chain wallet risk assessment and profiling.
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          description: Ethereum address to analyze.
        - name: chain
          in: query
          required: false
          schema:
            type: string
            default: base
          description: 'Target chain: base, ethereum, or sepolia.'
      responses:
        '200':
          description: Risk report data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.10'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/workflow/location-report:
    get:
      operationId: getLocationReport
      summary: Location intelligence report (forecast, air, flood, quakes, marine, solar).
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
          description: City or region name.
        - name: forecast_days
          in: query
          required: false
          schema:
            type: integer
            default: 3
          description: Days of forecast data (1-7).
      responses:
        '200':
          description: Comprehensive location data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.05'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/workflow/csv-to-pdf:
    post:
      operationId: csvToPdf
      summary: Convert uploaded CSV data to professional PDF report.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The CSV file.
                instructions:
                  type: string
                  description: JSON string containing processing/styling instructions.
              required:
                - file
      responses:
        '200':
          description: PDF report file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.15'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/price/btc-usd:
    get:
      operationId: getPricebtcusd
      summary: BTC/USD Price Feed Oracle
      description: Real-time BTC/USD price feed oracle.
      parameters: []
      responses:
        '200':
          description: Successful price retrieval
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/price/eth-usd:
    get:
      operationId: getPriceethusd
      summary: ETH/USD Price Feed Oracle
      description: Real-time ETH/USD price feed oracle.
      parameters: []
      responses:
        '200':
          description: Successful price retrieval
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/price/sol-usd:
    get:
      operationId: getPricesolusd
      summary: SOL/USD Price Feed Oracle
      description: Real-time SOL/USD price feed oracle.
      parameters: []
      responses:
        '200':
          description: Successful price retrieval
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/price/base-gas:
    get:
      operationId: getPricebasegas
      summary: Base Gas Price Oracle
      description: Real-time Base network gas price oracle.
      parameters: []
      responses:
        '200':
          description: Successful price retrieval
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/agent/status:
    get:
      operationId: getAgentStatus
      summary: Agent Status Check API
      description: Agent wallet status and readiness checker. Input any wallet address to get USDC/ETH balances, transaction count, wallet type, and personalized service recommendations.
      parameters:
        - name: wallet
          in: query
          required: true
          schema:
            type: string
          description: Ethereum wallet address to check (0x...)
      responses:
        '200':
          description: Successful status check
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/infra/health-check:
    get:
      operationId: getInfraHealthCheck
      summary: API Endpoint Health Checker
      description: API endpoint health checker and x402 compatibility scanner. Provide target url to fetch and check if it correctly implements the HTTP 402 payment flow, and extract its pricing requirements.
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
          description: Target API endpoint to scan
      responses:
        '200':
          description: Successful health scan
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/audit/agent-visibility:
    get:
      operationId: getAuditAgentVisibility
      summary: AEO/GEO Agent Visibility Auditor
      description: AEO/GEO Agent Visibility Auditor. Audit any third-party API endpoint for x402 compatibility, schema compliance, robots.txt indexing accessibility, and LLM tool calling clarity.
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
          description: Target API endpoint URL to check
      responses:
        '200':
          description: Successful health scan
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.75'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/infra/discover:
    get:
      operationId: getInfraDiscover
      summary: Agent Service Discovery Proxy
      description: Agent service discovery and search endpoint. Search and filter available x402 API endpoints by category, maximum query price, or keyword matches.
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: General keyword query to match names/descriptions
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: Filter by category (e.g. data/weather, blockchain)
        - name: max_price
          in: query
          required: false
          schema:
            type: string
          description: Maximum price filter in USDC (e.g. 0.005)
      responses:
        '200':
          description: Successful discovery query
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.02'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/watch/register:
    post:
      operationId: registerWatchSpec
      summary: Register a watch spec for real-time monitoring.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchSpec'
      responses:
        '201':
          description: Watch successfully registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  watchId:
                    type: string
                  checkEndpoint:
                    type: string
                  reused:
                    type: boolean
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
          - x402: {}
      security:
        - x402: []
    delete:
      operationId: cancelWatchSpec
      summary: Cancel and delete a watch spec (owner-only).
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          description: The watch ID to cancel.
      responses:
        '200':
          description: Watch successfully cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '404':
          description: Watch not found or unauthorized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/watch/check:
    get:
      operationId: checkWatch
      summary: Check a watch condition by ID.
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          description: The watch ID to check.
      responses:
        '200':
          description: Watch status evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchCheckResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '404':
          description: Watch not found or unauthorized
        '503':
          description: Upstream endpoint busy (free retry granted)
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.008'
        protocols:
          - x402: {}
      security:
        - x402: []
    head:
      operationId: preflightCheckWatch
      summary: Preflight authorization check for a watch ID (free).
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          description: The watch ID to preflight check.
      responses:
        '200':
          description: Authorized
        '404':
          description: Watch not found or unauthorized
  /api/watch/check-batch:
    get:
      operationId: checkWatchBatch
      summary: Batch check up to 5 watch conditions concurrently.
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated watch IDs to check (max 5).
      responses:
        '200':
          description: Batch results evaluated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WatchCheckResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.02'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/mock/social/feed:
    get:
      operationId: getMockSocialFeed
      summary: Mock Social Feed (Synthetic)
      description: Deterministic mock social feed generator for agent testing with persona, sentiment, seed, and custom formatting controls.
      parameters:
        - name: persona
          in: query
          schema:
            type: string
          description: Target persona (vitalikbuterin, brian_armstrong, elonmusk, saylor, cz_binance, trader_anon)
        - name: seed
          in: query
          schema:
            type: string
          description: Deterministic LCG seed value
        - name: sentiment
          in: query
          schema:
            type: string
          description: Sentiment bias (bullish, bearish, neutral)
        - name: count
          in: query
          schema:
            type: integer
          description: Number of tweets (1-20)
        - name: format
          in: query
          schema:
            type: string
          description: 'Output format: json | text'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/mock/social/stream:
    get:
      operationId: getMockSocialStream
      summary: Mock Social Stream Scenario
      description: Deterministic mock social scenario stream (hype cycle, FUD cascade, etc.) at specific step ticks.
      parameters:
        - name: scenario
          in: query
          schema:
            type: string
          description: Scenario name (hype_cycle, fud_cascade, regulatory_crackdown, quiet_accumulation)
        - name: step
          in: query
          schema:
            type: integer
          description: Scenario step (0-10)
        - name: seed
          in: query
          schema:
            type: string
          description: LCG seed value
        - name: format
          in: query
          schema:
            type: string
          description: 'Output format: json | text'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/news/crypto:
    get:
      operationId: getCryptoNews
      summary: Real-time aggregated cryptocurrency news feed with sentiment analysis.
      parameters:
        - name: topic
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated keywords (e.g. 'bitcoin,ethereum')
        - name: since
          in: query
          required: false
          schema:
            type: string
          description: ISO timestamp or shorthand '1h', '6h', '24h'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: Max articles to return (1-50)
        - name: minSentiment
          in: query
          required: false
          schema:
            type: number
          description: Minimum sentiment score (-1 to 1)
        - name: maxSentiment
          in: query
          required: false
          schema:
            type: number
          description: Maximum sentiment score (-1 to 1)
      responses:
        '200':
          description: Aggregated news articles retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  articles:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        link:
                          type: string
                        source:
                          type: string
                        publishedAt:
                          type: string
                        summary:
                          type: string
                        alsoReportedBy:
                          type: integer
                        sentimentScore:
                          type: number
                        sentimentLabel:
                          type: string
                        scoredTerms:
                          type: array
                          items:
                            type: string
                  meta:
                    type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.008'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/news/pulse:
    get:
      operationId: getNewsPulse
      summary: Synthesized news coverage metrics, volume velocity, and sentiment aggregates.
      parameters:
        - name: topic
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated keywords
        - name: window
          in: query
          required: false
          schema:
            type: string
            default: 6h
          description: Timeframe window '1h', '6h', '24h'
      responses:
        '200':
          description: News pulse aggregate retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  topic:
                    type: string
                  window:
                    type: string
                  articleCount:
                    type: integer
                  clusterCount:
                    type: integer
                  sentiment:
                    type: object
                  velocity:
                    type: object
                  topSources:
                    type: array
                    items:
                      type: object
                  topHeadlines:
                    type: array
                    items:
                      type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.02'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/report/agent-spend:
    get:
      operationId: getAgentSpendReport
      summary: Resolves on-chain USDC outflows to named merchants and listed services. JSON = $0.10, PDF = $0.25.
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          description: Target EVM wallet address to analyze
        - name: days
          in: query
          required: false
          schema:
            type: integer
            default: 30
          description: History query window (7-90 days)
        - name: format
          in: query
          required: false
          schema:
            type: string
            default: json
          description: 'Output format: ''json'' ($0.10) or ''pdf'' ($0.25)'
      responses:
        '200':
          description: Agent spend report returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  totalSpendUsdc:
                    type: number
                  txCount:
                    type: integer
                  byMerchant:
                    type: array
                    items:
                      type: object
                  resolutionRate:
                    type: number
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.50'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/trends/category:
    get:
      operationId: getCategoryTrends
      summary: Historical metrics, active listings share, price distribution, and call volume momentum.
      parameters:
        - name: tag
          in: query
          required: true
          schema:
            type: string
          description: Bazaar tag or category name to analyze
        - name: window
          in: query
          required: false
          schema:
            type: integer
            default: 7
          description: Number of snapshot dates to trace (7-30)
      responses:
        '200':
          description: Category trends aggregate retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  tag:
                    type: string
                  momentum:
                    type: object
                  pricingGuidance:
                    type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.25'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/trends/competitors:
    get:
      operationId: getListingCompetitors
      summary: Finds the closest competitor listings by tag overlap and semantic token similarity.
      parameters:
        - name: resource
          in: query
          required: false
          schema:
            type: string
          description: Listing resource URL to analyze
        - name: payTo
          in: query
          required: false
          schema:
            type: string
          description: Merchant payTo address to analyze
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
          description: Max competitors to return (1-25)
      responses:
        '200':
          description: Listing competitor set retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  competitors:
                    type: array
                    items:
                      type: object
                  marketPosition:
                    type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.50'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/market/history:
    get:
      operationId: getMarketHistory
      summary: Historical time series of the x402 Bazaar, reconstructed from daily snapshots. Per-day ecosystem GMV, merchant and listing counts, price-band distribution and median/P90 pricing; per-merchant lifecycle with first-seen, last-seen and departure; every observed price change with date and magnitude; and the biggest movers ranked by change in unique paying wallets rather than call count. The Coinbase discovery API returns only the current catalogue and keeps no archive.
      parameters:
        - name: days
          in: query
          required: false
          schema:
            type: integer
            maximum: 400
          description: Limit to the most recent N daily snapshots. Omit for the full archive.
        - name: merchant
          in: query
          required: false
          schema:
            type: string
          description: Optional domain filter, e.g. example.com, to scope merchant and price detail.
      responses:
        '200':
          description: Historical market report
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '503':
          description: Snapshot archive temporarily unavailable; not charged, safe to retry
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '25.00'
        protocols:
          - x402: {}
      security:
        - x402: []
  /api/market/listing-intel:
    get:
      operationId: getListingIntel
      summary: 'Audit your own x402 Bazaar listings: authenticity scoring that separates genuine demand from self-traffic, per-listing health diagnostics, price-band guidance from what measurably sells, and your revenue percentile across all indexed merchants.'
      parameters:
        - name: domain
          in: query
          required: false
          schema:
            type: string
          description: Merchant domain to audit, e.g. example.com. Provide this or pay_to.
        - name: pay_to
          in: query
          required: false
          schema:
            type: string
          description: Receiving wallet address (0x...) whose listings should be audited.
        - name: tag
          in: query
          required: false
          schema:
            type: string
          description: Optional keyword to scope pricing guidance to comparable services.
      responses:
        '200':
          description: Listing intelligence report
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '503':
          description: Snapshot archive temporarily unavailable; not charged, safe to retry
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '1.00'
        protocols:
          - x402: {}
      security:
        - x402: []
components:
  schemas:
    PaymentRequired:
      type: object
      properties:
        x402Version:
          type: integer
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              network:
                type: string
              maxAmountRequired:
                type: string
              resource:
                type: string
              description:
                type: string
              payTo:
                type: string
              asset:
                type: string
        facilitatorUrl:
          type: string
    WeatherResult:
      type: object
      properties:
        location:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        days:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              temp_max_c:
                type: number
              temp_min_c:
                type: number
              precipitation_mm:
                type: number
              condition:
                type: string
        summary:
          type: object
          properties:
            avg_temp_c:
              type: number
            total_precipitation_mm:
              type: number
            days_with_rain:
              type: integer
    CsvResult:
      type: object
      properties:
        status:
          type: string
        stats:
          type: object
          properties:
            rowsBefore:
              type: integer
            rowsAfter:
              type: integer
            issuesFixed:
              type: integer
            columns:
              type: integer
        data:
          type: array
          items:
            type: object
    RiskResult:
      type: object
      properties:
        address:
          type: string
        network:
          type: string
        riskScore:
          type: integer
        riskLevel:
          type: string
          enum:
            - critical
            - high
            - medium
            - low
            - minimal
        flags:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              severity:
                type: string
                enum:
                  - critical
                  - high
                  - medium
                  - low
                  - info
              label:
                type: string
              detail:
                type: string
        profile:
          type: object
          properties:
            type:
              type: string
              enum:
                - eoa
                - contract
                - empty
            balanceEth:
              type: string
            balanceWei:
              type: string
            transactionCount:
              type: integer
            hasCode:
              type: boolean
            codeSize:
              type: integer
            isProxy:
              type: boolean
            implementationAddress:
              type: string
              nullable: true
        metadata:
          type: object
          properties:
            queriedAt:
              type: string
              format: date-time
            processingTime:
              type: string
            signalsAnalyzed:
              type: integer
            warnings:
              type: array
              items:
                type: string
    WalletIntelResult:
      type: object
      properties:
        address:
          type: string
        chain:
          type: string
        profile:
          type: object
          properties:
            type:
              type: string
              enum:
                - eoa
                - contract
                - empty
            balanceEth:
              type: string
            balanceUsd:
              type: string
            transactionCount:
              type: integer
            isContract:
              type: boolean
            walletAge:
              type: string
        tokens:
          type: array
          items:
            type: object
            properties:
              symbol:
                type: string
              name:
                type: string
              balance:
                type: string
              contractAddress:
                type: string
        activity:
          type: object
          properties:
            totalTransactions:
              type: integer
            level:
              type: string
              enum:
                - empty
                - new
                - moderate
                - active
                - whale
            tags:
              type: array
              items:
                type: string
        metadata:
          type: object
          properties:
            queriedAt:
              type: string
              format: date-time
            processingTime:
              type: string
            dataSource:
              type: string
            warnings:
              type: array
              items:
                type: string
    DefiYieldsResponse:
      type: object
      properties:
        count:
          type: integer
        filters:
          type: object
          properties:
            token:
              type: string
            chain:
              type: string
              nullable: true
            min_tvl:
              type: integer
        yields:
          type: array
          items:
            type: object
            properties:
              protocol:
                type: string
              chain:
                type: string
              pool:
                type: string
              symbol:
                type: string
              apy:
                type: number
              apyBase:
                type: number
                nullable: true
              apyReward:
                type: number
                nullable: true
              tvl:
                type: number
              tvlFormatted:
                type: string
              riskLevel:
                type: string
              poolType:
                type: string
              url:
                type: string
        source:
          type: string
        processingTime:
          type: string
    GasOracleResponse:
      type: object
      properties:
        chain:
          type: string
        blockNumber:
          type: integer
        timestamp:
          type: string
          format: date-time
        gasPrice:
          type: object
          properties:
            slow:
              type: object
              properties:
                gwei:
                  type: number
                maxFee:
                  type: number
                maxPriorityFee:
                  type: number
                estimatedSeconds:
                  type: integer
            standard:
              type: object
              properties:
                gwei:
                  type: number
                maxFee:
                  type: number
                maxPriorityFee:
                  type: number
                estimatedSeconds:
                  type: integer
            fast:
              type: object
              properties:
                gwei:
                  type: number
                maxFee:
                  type: number
                maxPriorityFee:
                  type: number
                estimatedSeconds:
                  type: integer
        estimatedCosts:
          type: object
          properties:
            ethTransfer:
              type: object
              properties:
                slow:
                  type: string
                standard:
                  type: string
                fast:
                  type: string
            erc20Transfer:
              type: object
              properties:
                slow:
                  type: string
                standard:
                  type: string
                fast:
                  type: string
            swap:
              type: object
              properties:
                slow:
                  type: string
                standard:
                  type: string
                fast:
                  type: string
        networkStatus:
          type: string
        recommendation:
          type: string
        source:
          type: string
        processingTime:
          type: string
    WatchSpec:
      type: object
      required:
        - kind
        - target
        - condition
      properties:
        kind:
          type: string
          enum:
            - price
            - gas
            - weather
            - wallet
            - endpoint
            - news
        target:
          type: string
          description: Kind-specific target details
        condition:
          type: object
          required:
            - op
            - field
          properties:
            op:
              type: string
              enum:
                - gt
                - lt
                - crosses
                - changes
            field:
              type: string
            value:
              type: number
        notify:
          type: object
          properties:
            email:
              type: string
              format: email
        authorizedPayers:
          type: array
          items:
            type: string
    WatchCheckResult:
      type: object
      properties:
        watchId:
          type: string
          format: uuid
        kind:
          type: string
        target:
          type: string
        triggered:
          type: boolean
        delta:
          type: object
          nullable: true
          properties:
            prev:
              type: object
              nullable: true
            curr:
              type: object
        checkedAt:
          type: integer
        error:
          type: string
  securitySchemes:
    x402:
      type: apiKey
      name: X-Payment
      in: header
      description: Base64 encoded x402 payment payload signed by the agent wallet.