HumanMirror Referral API

openapi: 3.2.0
info:
  title: HumanMirror x402 Referral 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: Referral
paths:
  /api/referral/create/:
    post:
      summary: Create an Enterprise referral identifier
      description: Requires an active Enterprise Bearer token. Creates a signed referral identifier bound to the referrer.
      responses:
        '200':
          description: Referral identifier created.
        '401':
          description: Active Enterprise pass required.
      tags:
      - Referral
      operationId: postApiReferralCreate
      x-operation-id-source: derived
  /api/referral/status/:
    get:
      summary: Read Enterprise referral rewards
      responses:
        '200':
          description: Referral reward ledger.
        '401':
          description: Active Enterprise pass required.
      tags:
      - Referral
      operationId: getApiReferralStatus
      x-operation-id-source: derived
  /api/referral/claim/:
    post:
      summary: Claim credited referral days
      description: Claims all unclaimed 30-day rewards and returns a replacement Enterprise Bearer token with extended expiry.
      responses:
        '200':
          description: Reward claim result.
        '401':
          description: Active Enterprise pass required.
      tags:
      - Referral
      operationId: postApiReferralClaim
      x-operation-id-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