Authentication

MainMarket accepts three independent auth paths. Pick the one that matches your deployment shape — they cannot be mixed in a single request.

• x402 / MPP wallet payment — recommended for autonomous agents and one-off integrations. No signup, pay-per-call.
• Internal token — for the MainMarket Cart app and other first-party services. Free.
• B2B API key — issued out-of-band for enterprise customers on a monthly contract. Bypasses per-call billing.

x402 wallet payment (recommended for agents)

MainMarket implements the x402 protocol on Base (USDC) and parallel MPP challenges on Tempo (USDC). Both flow through one 402 response — your client picks whichever rail it supports.

The challenge / proof / retry flow

1. Your client hits a paid route with no Authorization header.
2. The API responds 402 Payment Required with WWW-Authenticate and base64-encoded PAYMENT-REQUIRED headers describing the price, asset, and recipient address.
3. Your client signs a USDC transfer (x402) or signs an MPP intent, then retries the original request with the payment proof in Payment-Signature, X-Payment, or Authorization: Payment ....
4. The API verifies the proof with the facilitator, settles on-chain, and returns the original JSON response with a PAYMENT-RESPONSE receipt header.

Sample 402 response

HTTP/1.1 402 Payment Required
Content-Type: application/json
WWW-Authenticate: Payment realm="api.mainmarket.com", scheme="tempo", intent="charge", currency="USDC", asset="0x20C0...", amount="0.01", recipient="0x...", resource="https://api.mainmarket.com/v1/prices?q=milk", description="MainMarket GET /v1/prices"
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Miwi...
X-Request-ID: 4fe7...

{
  "error": "payment_required",
  "amount": "0.01",
  "currency": "USD",
  "asset": "USDC",
  "resource": "https://api.mainmarket.com/v1/prices?q=milk",
  "method": "GET",
  "description": "MainMarket GET /v1/prices",
  "accepts": [
    {
      "protocol": "x402",
      "version": 2,
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x...",
      "amount_raw": "10000"
    },
    {
      "protocol": "mpp",
      "scheme": "tempo",
      "intent": "charge",
      "asset": "0x20C0...",
      "recipient": "0x...",
      "amount": "0.01"
    }
  ]
}

Compatible clients

• AgentCash — hosted CLI, transparent payment, recommended for first calls.
• @coinbase/x402-fetch — drop-in fetch replacement for Node.
• x402 Python SDK — requests-style client.
• Privy embedded wallets, mppx, and any client that speaks x402 v2 — all interoperable.

Internal token (Cart app + first-party)

Internal services pass a shared bearer token prefixed with mm_internal_. This bypasses payment entirely; the token must match the API server's INTERNAL_API_TOKEN environment variable. Used by the consumer Cart app and any first-party MainMarket integration.

curl -H "Authorization: Bearer mm_internal_$INTERNAL_API_TOKEN" \
  'https://api.mainmarket.com/v1/prices?q=milk&store_id=4f2a...'

B2B API key (enterprise)

Enterprise customers receive a long-lived API key that bypasses per-call billing in exchange for a monthly contract. Keys are bcrypt-hashed in clients.api_key_hash and rotated on request.

curl -H "Authorization: Bearer $MM_API_KEY" \
  'https://api.mainmarket.com/v1/prices?q=milk&store_id=4f2a...'

Bypass priority

For each request to a paid route, the middleware checks in order:

1. Authorization: Bearer mm_internal_... matching the env token → bypass.
2. Any other Authorization: Bearer ... → bypass; downstream B2B bcrypt verification 401s if invalid.
3. X-Payment-Stub: allow when PAYMENT_STUB_ALLOW=true → bypass (local dev only).
4. Payment-Signature / X-Payment (x402) → verify and settle.
5. Authorization: Payment ... (MPP) → verify with pympp (stub today).
6. Otherwise → emit 402 with both protocol challenges.