openapi: 3.2.0
info:
  title: HumanMirror x402 M2m API
  version: 3.3.0
  description: 'HumanMirror Agent-First machine-payment API: M2M infrastructure on Base using x402 V2 and USDC, autonomous agent security, prompt injection defense, AI micro-transactions and non-custodial escrow preview. Granular calls use 0.001 / 0.010 / 0.050 USDC, thematic bundles 5.000 USDC, Enterprise Fleet 297.000 USDC / 30 days, plus the 2027-2030 Next-Gen preview suite at 0.050 USDC per test call.'
  x-keywords:
  - M2M infrastructure on Base
  - x402 payment protocol
  - Autonomous agent security
  - Prompt injection defense
  - AI micro-transactions and escrow
  - Intent-Proof
  - M2M Escrow
  - Consensus-Lock
  - Verified-savings best execution
  - Execution Market
  - provider competition
  x-guidance: Use HumanMirror x402 routes for deterministic payment compatibility, safety preflight, and execution verification. Start without PAYMENT-SIGNATURE to receive the x402 challenge, then retry with a valid Base/USDC payment. For the lowest-friction entry point, use /api/x402/payment-compatibility-receipt/ to validate a payment shape; use /api/x402/safe-preflight/ before consequential agent actions.
servers:
- url: https://humanmirror.fr
tags:
- name: M2m
paths:
  /api/v1/m2m/fallback/:
    get:
      operationId: discoverM2MFallback
      summary: Discover HumanMirror machine fallback normalizer
      responses:
        '200':
          description: Fallback routing metadata.
          content:
            application/json:
              schema:
                type: object
      tags:
      - M2m
    post:
      operationId: normalizeM2MFallback
      summary: Normalize malformed or adjacent machine requests and return resilience pointers
      responses:
        '200':
          description: Normalized request plus sink/x402 pointers.
          content:
            application/json:
              schema:
                type: object
      tags:
      - M2m
  /api/v1/m2m/bot-convert/:
    post:
      operationId: convertBotPayload
      summary: Convert common bot/agent payloads into canonical HumanMirror context requests
      responses:
        '200':
          description: Canonical machine request.
          content:
            application/json:
              schema:
                type: object
      tags:
      - M2m
  /api/v1/m2m/micro-work/claim/:
    get:
      operationId: claimMicroWork
      summary: Claim deterministic micro-work for one HumanMirror service execution credit
      responses:
        '200':
          description: Challenge issued
          content:
            application/json:
              schema:
                type: object
      tags:
      - M2m
  /api/v1/m2m/micro-work/submit/:
    post:
      operationId: submitMicroWork
      summary: Submit deterministic micro-work and receive one short-lived service credit
      responses:
        '200':
          description: Service credit issued
          content:
            application/json:
              schema:
                type: object
      tags:
      - M2m
  /api/v1/m2m/liquidity-status/:
    get:
      operationId: readLiquidityStatus
      summary: Read Base USDC balance for a supplied wallet
      parameters:
      - name: wallet
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Read-only balance result
          content:
            application/json:
              schema:
                type: object
      tags:
      - M2m
  /api/v1/m2m/payload-normalizer/:
    get:
      operationId: discoverPayloadNormalizer
      responses:
        '200':
          description: Discovery metadata
      deprecated: false
      description: 'Granular unit route at 0.001 USDC on Base mainnet. Upgrade path: https://humanmirror.fr/api/v1/agent/data-quality/'
      x-humanmirror-canonical-bundle: https://humanmirror.fr/api/v1/agent/data-quality/
      x-humanmirror-price-usdc: '0.001'
      x-humanmirror-pricing-tier: granular_unit_0_001
      tags:
      - M2m
      summary: Discover payload normalizer
      x-summary-source: derived
    post:
      operationId: normalizeM2MPayload
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - payload
              properties:
                payload: {}
                options:
                  type: object
                  properties:
                    trim_strings:
                      type: boolean
                      default: true
                    drop_nulls:
                      type: boolean
                      default: false
                    key_case:
                      type: string
                      enum:
                      - preserve
                      - snake_case
                      default: preserve
                  additionalProperties: false
              additionalProperties: false
      responses:
        '200':
          description: Canonical normalized payload
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid or oversized payload
        '402':
          description: Initial benchmark quota exhausted; x402 payment required
          headers:
            PAYMENT-REQUIRED:
              schema:
                type: string
        '503':
          description: Quota or payment facilitator unavailable
      deprecated: false
      description: 'Granular unit route at 0.001 USDC on Base mainnet. Upgrade path: https://humanmirror.fr/api/v1/agent/data-quality/'
      x-humanmirror-canonical-bundle: https://humanmirror.fr/api/v1/agent/data-quality/
      x-humanmirror-price-usdc: '0.001'
      x-humanmirror-pricing-tier: granular_unit_0_001
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        protocols:
        - x402: {}
      tags:
      - M2m
      summary: Normalize M2 MPayload
      x-summary-source: derived
components:
  securitySchemes:
    HumanMirrorProApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Active HumanMirror Pro API key. Grants Next-Gen Preview access subject to the Pro monthly API quota.
    EnterpriseBearer:
      type: http
      scheme: bearer
      bearerFormat: hmep1
      description: Active HumanMirror Enterprise Fleet pass. Next-Gen Preview is included.
    OmniSyncApiKey:
      type: http
      scheme: bearer
      bearerFormat: hm_omni_*
      description: HumanMirror Omni-Sync API key. One credit per Shared Context operation when credits are available.
externalDocs:
  description: HumanMirror — The Agent Economy (2027-2030) technical lexicon
  url: https://humanmirror.fr/future/
x-humanmirror-agent-manifest: https://humanmirror.fr/.well-known/agent-manifest.json
x-humanmirror-canonical-endpoints:
- id: security-intelligence
  url: https://humanmirror.fr/api/v1/agent/security-intelligence/
  price_usdc: '5.000'
  billing_unit: bundle
- id: data-quality
  url: https://humanmirror.fr/api/v1/agent/data-quality/
  price_usdc: '5.000'
  billing_unit: bundle
- id: verification
  url: https://humanmirror.fr/api/v1/agent/verification/
  price_usdc: '5.000'
  billing_unit: bundle
- id: operations
  url: https://humanmirror.fr/api/v1/agent/operations/
  price_usdc: '5.000'
  billing_unit: bundle
- id: enterprise-fleet
  url: https://humanmirror.fr/api/x402/enterprise-pass/
  price_usdc: '297.000'
  billing_unit: 30_days
x-humanmirror-pricing-ladder:
  granular_unit_tiers_usdc:
  - '0.001'
  - '0.010'
  - '0.050'
  thematic_bundle_usdc: '5.000'
  enterprise_fleet_usdc: '297.000'
x-humanmirror-next-gen-endpoints:
- id: next_gen_intent_proof
  url: https://humanmirror.fr/v1/agent/intent-proof/
  status: preview_2027_2030
  price_usdc: '0.050'
  enterprise_included: true
  pro_preview: true
- id: next_gen_consensus_lock
  url: https://humanmirror.fr/v1/fleet/consensus-lock/
  status: preview_2027_2030
  price_usdc: '0.050'
  enterprise_included: true
  pro_preview: true
- id: next_gen_escrow_settle
  url: https://humanmirror.fr/v1/m2m/escrow-settle/
  status: preview_2027_2030
  price_usdc: '0.050'
  enterprise_included: true
  pro_preview: true
x-humanmirror-provenance:
  owner: HumanMirror
  scheme: zero-width+HMAC-SHA256
  watermark_sha256: 8cf2f98bdc78f5034d0fc568f119d07fe18f884c4384d5df43d486e5659e9592
x-humanmirror-agent-first:
  future_lexicon: https://humanmirror.fr/future/
  llms: https://humanmirror.fr/llms.txt
  a2a: https://humanmirror.fr/.well-known/agent-card.json
  mcp: https://humanmirror.fr/api/x402/mcp/
x-humanmirror-core-products:
  shared_context:
    endpoint: https://humanmirror.fr/v1/agent/shared-context/
    manifest: https://humanmirror.fr/.well-known/shared-context.json
    price_usdc: '0.010'
    stripe_credits: true
  perception_behavior_vector:
    endpoint: https://humanmirror.fr/v1/agent/perception-vector/
    manifest: https://humanmirror.fr/.well-known/perception-behavior.json
    price_usdc: '0.050'
    privacy_mode: aggregate_cohort_only
x-humanmirror-global-enterprise:
  version: 2026-09-04-v1
  manifest: https://humanmirror.fr/.well-known/global-enterprise.json
  profile_endpoint: https://humanmirror.fr/api/v1/global-enterprise/profile/
  billing_capabilities: https://humanmirror.fr/api/v1/global-enterprise/billing-capabilities/
  headers:
  - X-Industry-Profile
  - X-Jurisdiction
  - X-Billing-Currency
  built_in_profiles:
  - finance
  - pharma
  - retail
  - logistics
  - tech
  - entertainment
  custom_profiles: true
  compatibility: additive_no_header_no_behavior_change
  compliance_assurance: policy_guardrails_not_legal_certification
x-humanmirror-paid-retry:
  protocol: payment-bound-idempotency/1
  header: Idempotency-Key
  identity: method + canonical route + request-body digest + exact payment-authorization digest
  scope: canonical paid x402 POST routes
  replay_header: X-HumanMirror-Idempotent-Replay
  completed_replay_ttl_seconds: 86400
  processing_lock_ttl_seconds: 300
  semantics:
    exact_retry: returns the original verified successful response without a second execution or settlement
    altered_body: conflict; never replays unrelated output
    fresh_payment_authorization: new payment intent even if the Idempotency-Key is reused
    failed_execution_or_settlement: not committed as a successful replay
x-humanmirror-best-execution:
  protocol: hm-best-execution/1
  fee_model: verified_savings_share
  savings_share_bps: 3000
  buyer_keeps_share_bps: 7000
  quote_ttl_seconds: 120
  provider_payment: external_non_custodial
  manifest: https://humanmirror.fr/.well-known/intent-market.json
x-x402:
  payTo: '0x48096526488f2D51df6bcA1B1f3A3639986cc3dD'
  asset: USDC
  network: eip155:8453