openapi: 3.2.0
info:
  title: PaidHandshake Exchange Machine API
  version: 2.9.0
  description: Broad lawful paid public-web research and commercial-intelligence routing, verified data feeds, delegated machine payments and recurring watches for autonomous agents.
servers:
- url: https://paidhandshake.com
tags:
- name: Machine
paths:
  /api/machine/v1/wallet/topup/x402:
    post:
      operationId: fundMachineWalletX402
      summary: Fund an authenticated machine wallet with Base USDC via x402, no human checkout
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Wallet funded
        '402':
          description: PAYMENT-REQUIRED
        '503':
          description: x402 not active
      tags:
      - Machine
  /api/machine/v1/onboarding:
    get:
      operationId: getMachineOnboarding
      summary: Self-service machine buyer onboarding instructions
      responses:
        '200':
          description: Onboarding flow
      tags:
      - Machine
  /api/machine/v1/enroll:
    post:
      operationId: enrollMachineBuyer
      summary: Create a zero-balance machine identity
      responses:
        '200':
          description: Machine identity and one-time API key
      tags:
      - Machine
  /api/machine/v1/quote:
    post:
      operationId: quoteMachineJob
      summary: Get a free preflight quote for broad lawful paid worker fulfillment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MachineQuoteRequest'
      responses:
        '200':
          description: Estimated price
      tags:
      - Machine
  /api/machine/v1/capabilities:
    get:
      operationId: getMachineCapabilities
      summary: Describe machine-payment capabilities
      responses:
        '200':
          description: Machine capabilities
      tags:
      - Machine
  /api/machine/v1/jobs:
    post:
      operationId: submitMachineJob
      summary: Submit a machine-authorized custom or standard paid job
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MachineJobRequest'
      responses:
        '200':
          description: Queued or quoted job
        '402':
          description: Additional funding or authority required
      tags:
      - Machine
  /api/machine/v1/jobs/{job_id}:
    get:
      operationId: getMachineJob
      summary: Poll a machine job
      security:
      - bearerAuth: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job status/result
      tags:
      - Machine
  /api/machine/v1/wallet:
    get:
      operationId: getMachineWallet
      summary: Read machine wallet and limits
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Wallet
      tags:
      - Machine
  /api/machine/v1/watches:
    get:
      operationId: listMachineWatches
      summary: List recurring paid watches
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Watches
      tags:
      - Machine
    post:
      operationId: createMachineWatch
      summary: Create a recurring paid watch
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringWatchRequest'
      responses:
        '200':
          description: Created watch
      tags:
      - Machine
  /api/machine/v1/watches/{watch_id}:
    get:
      operationId: getMachineWatch
      summary: Get one recurring paid watch
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Watch
      tags:
      - Machine
  /api/machine/v1/watches/{watch_id}/enable:
    post:
      operationId: enableMachineWatch
      summary: Enable a watch
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Enabled watch
      tags:
      - Machine
  /api/machine/v1/watches/{watch_id}/disable:
    post:
      operationId: disableMachineWatch
      summary: Disable a watch
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Disabled watch
      tags:
      - Machine
components:
  schemas:
    RecurringWatchRequest:
      type: object
      required:
      - query
      - max_price_cents
      properties:
        name:
          type: string
        query:
          type: string
          maxLength: 1200
        task_type:
          type: string
        cadence_minutes:
          type: integer
          minimum: 60
          maximum: 10080
        max_price_cents:
          type: integer
          minimum: 1
        run_immediately:
          type: boolean
    MachineJobRequest:
      type: object
      required:
      - query
      - max_price_cents
      properties:
        query:
          type: string
          minLength: 3
          maxLength: 1200
        task_type:
          type: string
        constraints:
          type: object
        max_price_cents:
          type: integer
          minimum: 1
        idempotency_key:
          type: string
          maxLength: 120
    MachineQuoteRequest:
      type: object
      required:
      - task_type
      properties:
        task_type:
          type: string
        query:
          type: string
          maxLength: 1200
        constraints:
          type: object
        max_price_cents:
          type: integer
          minimum: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: One-time-issued phm_ machine API key. Store securely; PaidHandshake stores only a hash.