Mercury Hq Com Authentication

generated: '2026-09-19'
method: searched
source:
- openapi/mercury-hq-com-x402-storefront-openapi.yml (NO securitySchemes and no security requirements; per-operation x-payment-info / x-x402 declare the payment terms instead)
- live unpaid GET https://network.mercury-hq.com/buy/fetch?url=https://example.com -> 402 {x402Version 1, error "X-PAYMENT header is required", accepts[]}
- https://network.mercury-hq.com/developers and /university/developers (API-key rail: mk_test_/mk_live_ Bearer keys, POST /api/dev/keys)
- "https://network.mercury-hq.com/.well-known/agent-card.json (securitySchemes.x402, security [{x402: []}])"
- POST https://network.mercury-hq.com/mcp initialize / tools/list (anonymous) and GET /mcp descriptor ("tools/call needs a Mercury API key (Authorization: Bearer mk_…)")
- https://registry.npmjs.org/mercury-x402-mcp (stdio server pays from MERCURY_PRIVATE_KEY)
- GET https://network.mercury-hq.com/api/dev/balance -> 401 without a key
docs: https://network.mercury-hq.com/university/developers
description: >-
  MERCURY has no credential to obtain before calling: the contract is payment-as-authorization. An unpaid
  request to any paid /buy/* route is answered HTTP 402 with an x402 v1 challenge and succeeds when
  replayed with an X-PAYMENT header carrying a signed USDC payment for the exact amount. As an
  alternative "door" the same routes accept a Mercury API key as a Bearer token - a free sandbox key
  (mk_test_, 100 credits) minted with one anonymous POST, or a Stripe-billed live key (mk_live_). The
  hosted MCP server gates tools/call on that same key while leaving initialize and tools/list open; the
  stdio MCP package instead pays over x402 from a wallet private key. Discovery, verification and the A2A
  free preview are anonymous. No OAuth 2.0, OpenID Connect, mutual TLS or per-user identity exists
  anywhere, and the OpenAPI declares none of this - its securitySchemes are absent, which is the gap an
  agent reading only the spec would hit. derive-authentication.py therefore produced no baseline; this
  profile is written from the docs and the wire.
summary:
  types: [x402-payment, apiKey, none]
  api_key_in: [header]
  api_key_header: 'Authorization: Bearer mk_test_... | mk_live_...'
  oauth2_flows: []
  openapi_security_schemes_declared: 0
schemes:
- name: x402
  type: payment (x402)
  surface: all 18 paid /buy/* operations (buy_web_fetch ... buy_cited_redirect); the A2A card's declared scheme for the paid result
  description: >-
    Unpaid call -> 402 application/json {x402Version: 1, error: "X-PAYMENT header is required", accepts:
    [{scheme: exact, network: base, maxAmountRequired: "<USDC base units, 6 decimals>", resource, payTo:
    0xe10B9d44e72A29B9c19da02981FFCd875308e3C1, maxTimeoutSeconds: 60, asset:
    0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, outputSchema, extra: {name: USD Coin, version: 2}}]}. The
    client signs an EIP-3009 style USDC transfer for the amount with any x402 client (the docs show
    x402-fetch wrapFetchWithPayment with a viem account; x402-axios also named) and replays the request
    with the X-PAYMENT header; settlement goes through the Coinbase CDP facilitator
    (https://api.cdp.coinbase.com/platform/v2/x402) on Base mainnet (eip155:8453), testnet false. The
    price is declared per operation in x-payment-info / x-x402 and in /catalog and /.well-known/x402; the
    challenge carries the same number. No account, no key, no signup. /buy/fetch offers three accepts
    tiers (3000 / 6000 / 12000 base units). The agent card expresses this as securitySchemes.x402 {type:
    x402, scheme: exact, network: eip155:8453, asset: USDC} with security [{x402: []}].
  sources: [openapi/mercury-hq-com-x402-storefront-openapi.yml, a2a/mercury-hq-com-agent-card.json, well-known/mercury-hq-com-x402.json]
  probe: {url: 'https://network.mercury-hq.com/buy/fetch?url=https://example.com', method: 'GET (unpaid)', status: 402, x402Version: 1, maxAmountRequired: '3000'}
- name: mercuryApiKey
  type: apiKey
  in: header
  parameter: 'Authorization: Bearer <key>'
  key_prefixes: [mk_test_, mk_live_]
  surface: the same 18 /buy/* routes; POST /mcp tools/call; the key-management routes /api/dev/keys, /api/dev/balance, /api/dev/topup (outside the OpenAPI)
  description: >-
    "Prefer a prepaid key? The same routes accept Authorization: Bearer mk_live_... - issue one at
    /developers." Issuance: POST /api/dev/keys?live=false&label=... (anonymous) returns 201 {ok, key, keyId,
    env, tail, usage, save_it}; the raw key is shown ONCE and only its sha256 plus a 4-character tail are
    stored; issuance is capped at 20 keys per IP per hour. Sandbox keys carry 100 credits at 5 requests
    per minute; live keys are enabled by a Stripe Checkout subscription (Pro $29 / Business $199 /
    Enterprise $1500 per month) or a one-time credit top-up, metered at 1 credit = $0.001 per call.
    Balance: GET /api/dev/balance (401 without a key, observed). The /university hub labels the paid tier
    "Building" while /developers and /pricing describe it as live - recorded as stated.
  sources: [https://network.mercury-hq.com/developers, https://network.mercury-hq.com/university/developers, https://network.mercury-hq.com/pricing]
  probe: {url: 'https://network.mercury-hq.com/api/dev/balance', method: GET, status: 401, credentials: none}
- name: mcpRemote
  type: apiKey (same Mercury key) over MCP
  surface: POST https://network.mercury-hq.com/mcp
  description: >-
    initialize and tools/list answered without credentials (18 tools with inputSchema); the server
    descriptor and initialize.instructions state that tools/call needs Authorization: Bearer mk_.... No
    OAuth: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server are 404 on
    the MCP host, so there is no RFC 9728 / dynamic client registration path - a client must hold a key
    minted out of band (or via the anonymous POST /api/dev/keys).
  sources: [mcp/mercury-hq-com-mcp.yml]
  probe: {url: 'https://network.mercury-hq.com/mcp', method: 'POST tools/list', status: 200, credentials: none}
- name: mcpStdioWallet
  type: wallet-key (x402 via environment)
  surface: npx -y mercury-x402-mcp
  description: 'The stdio server reads MERCURY_PRIVATE_KEY (a funded Base-mainnet wallet) and pays each tool call over x402 with x402-fetch; no Mercury key. mercury_catalog and mercury_verify work without a wallet (npm README; not run here).'
  sources: [packages/mercury-hq-com-packages.yml]
- name: anonymous
  type: none
  surface: GET /catalog, /.well-known/x402, /x402/discovery, /openapi.json, /llms.txt, /manifest, /health, /vs, /market, /scoreboard, /proof, /buy/signal ($0), /x402/attestation/sample, /x402/verify, POST /verify, POST /a2a message/send (free preview), GET /terms, /privacy, /trust
  description: Free, keyless discovery and receipt verification. The receipt verification needs no MERCURY call at all (offline EIP-191 ecrecover against the pinned key at /.well-known/mercury-attestation).
  sources: [https://network.mercury-hq.com/llms.txt]
receipt_verification:
  note: not an authentication scheme for callers but the trust anchor for results
  signer: '0xACB40253BD71Bb9a5d491b2c6EFF755F2A33Fc75'
  key_pin: https://network.mercury-hq.com/.well-known/mercury-attestation
  alg: EIP-191-personal_sign over "mercury-x402:fetch-attestation:v1\nurl=...\nstatus=...\nsha256=...\nfetchedAt=...\nnonce=..."
scopes: none (no OAuth; no scope surface - scopes/ deliberately not written)
cross_links:
  conventions: conventions/mercury-hq-com-conventions.yml
  plans: plans/mercury-hq-com-plans-pricing.yml
  rate_limits: rate-limits/mercury-hq-com-rate-limits.yml
  mcp: mcp/mercury-hq-com-mcp.yml
  agent_card: a2a/mercury-hq-com-a2a.yml