API Evangelist enhancements for the MERCURY x402 storefront API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the MERCURY x402 storefront API
  version: 1.0.0
extends: openapi/mercury-hq-com-x402-storefront-openapi.yml
x-generated: '2026-09-19'
x-method: generated
x-source: openapi/mercury-hq-com-x402-storefront-openapi.yml (verbatim harvest of https://network.mercury-hq.com/openapi.json; identical paths at https://mercury-x402-jed.fly.dev/openapi.json with that host in servers[])
actions:
- target: $.info
  update:
    x-apievangelist:
      catalog: https://apis.io/mercury-hq-com
      provider: MERCURY (Mercury Holdings Pty Ltd)
      maintainer: Kin Lane <kin@apievangelist.com>
      harvested_from: [https://network.mercury-hq.com/openapi.json]
      artifacts:
      - apis.yml
      - authentication/mercury-hq-com-authentication.yml
      - conventions/mercury-hq-com-conventions.yml
      - errors/mercury-hq-com-problem-types.yml
      - lifecycle/mercury-hq-com-lifecycle.yml
      - conformance/mercury-hq-com-conformance.yml
      - plans/mercury-hq-com-plans-pricing.yml
      - rate-limits/mercury-hq-com-rate-limits.yml
      - mcp/mercury-hq-com-mcp.yml
      - mcp/mercury-hq-com-tool-crosswalk.yml
      - a2a/mercury-hq-com-a2a.yml
      - skills/_index.yml
- target: $.info
  update:
    x-payment-challenge-observed:
      fetched: '2026-09-19'
      request: GET https://network.mercury-hq.com/buy/fetch?url=https://example.com (unpaid)
      status: 402
      body_shape: '{x402Version: 1, error: "X-PAYMENT header is required", accepts: [{scheme: exact, network: base, maxAmountRequired: "3000", resource, payTo, maxTimeoutSeconds: 60, asset, outputSchema{input, output}, extra{name: USD Coin, version: 2}}]}'
      note: The spec's 402 responses declare a description only ("Terms are in the challenge body (x402 v1)"); no schema, no headers. The live body is x402 v1 while /.well-known/x402 declares x402Version 2.
- target: $.info
  update:
    x-spec-gaps:
    - no components.securitySchemes although two credentials exist (X-PAYMENT x402 header; Authorization Bearer mk_ API key) - see authentication/mercury-hq-com-authentication.yml
    - no examples anywhere; a free real sample response exists at https://network.mercury-hq.com/x402/attestation/sample
    - no 4xx other than 402 declared; observed 404 {ok,error,status,discovery,hint}, 503 mint-disabled (Retry-After 3600) on gated SKUs, 401 on /api/dev/*
    - 11 of 18 paid operations omit the attestation object from their 200 schema although the docs state every paid result ships one
    - the key-management routes POST /api/dev/keys, GET /api/dev/balance, POST /api/dev/topup are not in the spec
    - no tags object at the document level; operation tags are free-form marketing tags (up to 17 per operation)
- target: $.components
  update:
    securitySchemes:
      x402Payment:
        type: apiKey
        in: header
        name: X-PAYMENT
        description: 'API Evangelist annotation (not declared by the provider): x402 v1 signed payment payload; obtain terms from the 402 challenge; scheme exact, USDC on Base mainnet (eip155:8453).'
      mercuryApiKey:
        type: http
        scheme: bearer
        description: 'API Evangelist annotation (not declared by the provider): Mercury API key mk_test_ (free sandbox, 100 credits) or mk_live_ (Stripe-billed), from https://network.mercury-hq.com/developers.'
- target: $.paths['/buy/fetch'].get
  update:
    x-apievangelist-notes:
      mcp_tool: fetch
      a2a_skill: web-fetch (agent card; message/send free preview)
      x402_tiers: [fetch $0.003, plus $0.006, pro $0.012]
      idempotency: none - every settled attempt is charged and non-refundable
- target: $.paths['/buy/signal'].get
  update:
    x-apievangelist-notes:
      price: $0
      note: free demo read on static sample data; no MCP tool; not a market feed (provider disclaimer)
- target: $.paths['/buy/dns'].get
  update:
    x-apievangelist-notes:
      note: newest SKU (absent from the June 2026 stdio package README's 17 tools); either domain or url is required though neither is marked required in the spec
- target: $.paths['/buy/notarize'].get
  update:
    x-apievangelist-notes:
      note: exactly one of url or content must be supplied; the spec marks neither required