openapi: 3.1.0
info:
  title: HumanMirror Physical Oracle API
  version: 1.0.0-beta
  description: Non-custodial A2H field verification for autonomous agents and businesses.
servers:
- url: https://humanmirror.fr
paths:
  /api/physical-oracle/:
    get:
      summary: Discover Physical Oracle
      responses:
        '200':
          description: Discovery
  /api/physical-oracle/quote/:
    post:
      summary: Quote a public physical verification mission
      responses:
        '200':
          description: Quote and observed field supply
        '422':
          description: Unsafe or invalid mission
  /api/physical-oracle/missions/:
    post:
      summary: Create a mission
      responses:
        '201':
          description: Mission created; buyer key returned once
    get:
      summary: Read buyer mission state
      responses:
        '200':
          description: Mission state
  /api/physical-oracle/workers/register/:
    post:
      summary: Register a field executor
      responses:
        '201':
          description: Field key returned once
  /api/physical-oracle/workers/snapshot/:
    get:
      summary: List compatible missions for a field executor
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Worker profile and missions
  /api/physical-oracle/claim/:
    post:
      summary: Claim one mission for 20 minutes
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Mission and one-time claim nonce
  /api/physical-oracle/submit/:
    post:
      summary: Submit bounded photo evidence
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Proof submitted
  /api/physical-oracle/verify/:
    post:
      summary: Buyer accepts or rejects submitted evidence
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Decision and signed physical receipt
  /api/physical-oracle/commission/:
    post:
      summary: Pay accepted-mission HumanMirror commission over x402
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Commission settled
        '402':
          description: x402 payment required
  /api/physical-oracle/payout-confirm/:
    post:
      summary: Verify direct Base USDC payout to field executor
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Mission settled
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-humanmirror:
  protocol: humanmirror-physical-oracle/1
  custody: non_custodial
  worker_percent: 80
  platform_percent: 20
  network: eip155:8453
  asset: USDC