# Auth.md — Authentication

Payment/protocol mechanics only — for how the trust score itself is computed, see [methodology](https://gradientdecisions.com/methodology).

x402 Merchant Check has no accounts, no API keys, and no OAuth. There is nothing to register or log into.

Every call to the `check_merchant` MCP tool is authenticated by payment itself, per the [x402 protocol](https://x402.org): each request is paid for individually, on-chain, in USDC on Base mainnet. There's no session and no token beyond the payment itself.

## Registration

There is no registration step. No sign-up form, no account creation, no API key issuance, nothing to do in advance. Payment (see below) is the entire authentication mechanism — an agent goes from "never seen this service before" to "successfully authenticated and paid" in one HTTP round-trip.

## How it works

1. Call `check_merchant` on `https://mcp.gradientdecisions.com/mcp` with a `merchant_wallet_address`.
2. Without payment attached, the tool returns an x402 `402 Payment Required` challenge (an `accepts[]` array with `scheme`, `network`, `amount`, `asset`, `payTo`).
3. Build and sign a payment matching those exact terms, and retry the same call with it attached. See [x402.org](https://x402.org) or the [@x402/mcp](https://www.npmjs.com/package/@x402/mcp) client library for the mechanics — this server uses the official x402/MCP stack on the server side, not a custom variant.
4. On a valid payment, the tool settles it and returns the real result.

Price: **$0.01 USDC per call**, paid via x402 on Base mainnet (`eip155:8453`).

## Sample call and output

Illustrative only — not a live query, not real merchant data. Real results are only ever returned for an actual paid call.

Input:

```json
{
  "merchant_wallet_address": "0xffc458db291b4abce020fe3de4f91f2770e537b1",
  "price": 0.05
}
```

Output:

```json
{
  "merchant": "0xffc458db291b4abce020fe3de4f91f2770e537b1",
  "network": "eip155:8453",
  "recommendation": "PROCEED",
  "trust_tier": "TRUSTED",
  "confidence": "HIGH",
  "data_sufficiency": "SUFFICIENT",
  "signals": {
    "merchant_age_days": 184,
    "unique_payers": 51,
    "total_tx_count": 89635,
    "payer_concentration": "LOW"
  },
  "risk_flags": [],
  "reasons": [
    "Consistent signals across wallet age, payer diversity, and settlement history"
  ],
  "price_fairness": "fair",
  "pricing": {
    "advertised_prices_atomic": [
      50000
    ],
    "fairness_vs_category": "fair"
  },
  "category": "data_api",
  "chain": "base",
  "platforms": [
    {
      "url": "https://api.example.com/v1/weather",
      "serviceName": "Weather API"
    }
  ]
}
```

## Machine-readable discovery

- API catalog: [`/.well-known/api-catalog`](https://gradientdecisions.com/.well-known/api-catalog)
- Aggregate stats (no auth needed): [`https://gradientdecisions.com/`](https://gradientdecisions.com/) (send `Accept: text/markdown` for a plain-text version)