# `verify_merchant`

Answers whether an AI agent should proceed with a merchant. Returns a single `allow`
boolean plus plain-language reasons, backed by the signed
[verification record](../../api/verify.md).

**Tier:** read · **Rate limit:** ~30/min

## Input

| Param | Type | Required | Notes |
|---|---|---|---|
| `domain` | string | ✅ | Merchant hostname, e.g. `acme.com` |
| `min_tier` | `bronze` \| `silver` \| `gold` | — | Refuse unless the merchant meets at least this tier |

## Output

```json
{
  "allow": true,
  "status": "verified",
  "tier": "silver",
  "score": 63,
  "max_score": 100,
  "reasons": ["…"],
  "record": { }
}
```

`record` is the full signed verification record. `max_score` is always 100.

## Tier bands

| Tier | Score |
|---|---|
| `gold` | ≥ 80 |
| `silver` | ≥ 50 |
| `bronze` | ≥ 1 |
| `null` | 0, or no score |

## The default is permissive

!!!danger Read this before wiring it into a transaction gate
Without `min_tier`, `allow` is **`true`** unless there is a positive adverse finding. A
low score does not refuse. An `unverified` merchant — one never audited — does not
refuse; it adds an explanatory reason and allows.

This is deliberate. A default-deny on an unaudited domain would mean this tool blocks
most of the internet, which makes it an availability hazard rather than a safety check.

**If you want it to gate, you must pass `min_tier`.** With `min_tier` set, a merchant
whose tier is `null` — including every unaudited merchant — is refused.
!!!

| Status | Meaning | Refuses by default? |
|---|---|---|
| `verified` | Audited, evidence passed | No |
| `provisional` | Audited, evidence thin — tier forced to `null` | No |
| `unverified` | Never audited | No |
| `flagged` | Positive adverse finding | Yes |

## Errors

`NOT_FOUND` — `"<domain>" is not a valid hostname` for a malformed domain. A valid but
unknown domain is **not** an error; it returns `status: "unverified"`.