vibesprings-net Watch API

openapi: 3.2.0
info:
  title: Vibe Springs Watch 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
tags:
- name: Watch
paths:
  /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: []
      tags:
      - Watch
    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: []
      tags:
      - Watch
  /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: []
      tags:
      - Watch
    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
      tags:
      - Watch
  /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: []
      tags:
      - Watch
components:
  schemas:
    WatchCheckResult:
      type: object
      properties:
        watchId:
          type: string
          format: uuid
        kind:
          type: string
        target:
          type: string
        triggered:
          type: boolean
        delta:
          type:
          - object
          - 'null'
          properties:
            prev:
              type:
              - object
              - 'null'
            curr:
              type: object
        checkedAt:
          type: integer
        error:
          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
    PaymentRequired:
      type: object
      description: x402 v2 payment requirements. Sent base64-encoded JSON in the PAYMENT-REQUIRED response header of a 402. Retry the request with a PAYMENT-SIGNATURE header (v1 X-PAYMENT is also accepted).
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          enum:
          - 2
        error:
          type: string
        resource:
          type: object
          properties:
            url:
              type: string
            description:
              type: string
            mimeType:
              type: string
        accepts:
          type: array
          items:
            type: object
            required:
            - scheme
            - network
            - amount
            - asset
            - payTo
            properties:
              scheme:
                type: string
                example: exact
              network:
                type: string
                example: eip155:8453
                description: CAIP-2 network id (Base mainnet)
              amount:
                type: string
                description: Atomic units of asset (USDC has 6 decimals)
              asset:
                type: string
                description: Token contract address
              payTo:
                type: string
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                additionalProperties: true
        extensions:
          type: object
          additionalProperties: true
  securitySchemes:
    x402:
      type: apiKey
      name: X-Payment
      in: header
      description: Base64 encoded x402 payment payload signed by the agent wallet.