#Check a seller

Assess a seller or online store and return a trust assessment with supporting facts.

##What this endpoint does

Endpoint

```
POST https://mcp.gaisho.co/v1/tools/vet_seller
```

Assess the seller behind a listing or an online store, separately from the quality of the product it sells. The result identifies who was checked, gives a trust assessment and explains the available supporting facts and buyer considerations.

• -Check a marketplace seller before buying an unusually cheap listing.
• -Research an unfamiliar independent online store.
• -Resolve an ambiguous store name using a precise domain or seller page.

##Before you call

• -An offer ID, seller ID or seller page from search_products, get_offer or find_deals is more specific than a store name; an offer ID checks the seller of that offer. A marketplace product page may be useful, but confirm that the returned seller is the seller the shopper intends to use.
• -Acceptable inputs include an offer ID, account key, seller ID, marketplace seller page, product page, store domain, store URL or store name. Do not substitute a product rating for seller information.
• -If several sellers share a name, retry with a specific domain or one of the identities in the returned message.

Send a JSON object as the request body and authenticate with Authorization: Bearer <API key>. Amounts are in USD unless the result explicitly says otherwise.

##Request body

##Example request

Set GAISHO_API_KEY in your server or local environment. These examples use a JSON POST request; Python uses the standard library and JavaScript uses Node.js fetch. The 60-second client timeout in Python and JavaScript is configurable, not a service latency guarantee.

cURL

```
curl --fail-with-body 'https://mcp.gaisho.co/v1/tools/vet_seller' \
  -H "Authorization: Bearer $GAISHO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "seller": "https://www.walmart.com"
}'
```

Python

```
import json
import os
import urllib.error
import urllib.request

arguments = json.loads(r'''{
  "seller": "https://www.walmart.com"
}''')
request = urllib.request.Request(
    "https://mcp.gaisho.co/v1/tools/vet_seller",
    data=json.dumps(arguments).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["GAISHO_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        payload = json.load(response)
    print(json.dumps(payload, indent=2))
except urllib.error.HTTPError as error:
    print(error.read().decode("utf-8"))
    raise
```

JavaScript

```
// Node.js 18+; keep this code and the key on your server.
const response = await fetch("https://mcp.gaisho.co/v1/tools/vet_seller", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GAISHO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "seller": "https://www.walmart.com"
}),
  signal: AbortSignal.timeout(60_000),
});
const body = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${body}`);
}
const payload = JSON.parse(body);
console.log(payload);
```

##Common request patterns

###Check a marketplace seller

Replace the placeholder with the seller account key returned for the listing.

JSON request body

```
{
  "seller": "amazon.com:SELLER_ID_FROM_OFFER"
}
```

##Response fields

The HTTP response contains tool and result. All fields below the envelope, including any assessment summary, are inside result.

##Example response

Examples are illustrative and may omit optional detail fields. Prices are not live quotes; identifiers and example.com URLs are placeholders to replace, not usable product records.

HTTP 200 · illustrative, shortened

```
{
  "tool": "vet_seller",
  "result": {
    "status": "found",
    "message": null,
    "seller_key": "shopify:SELLER_ID",
    "seller_name": "Example Store",
    "seller_url": "https://example.com",
    "trust_level": "trusted",
    "trust_label": "Trusted",
    "summary": "Trusted: the official store of Example; prices in line with major retailers (24 items compared). Buyer notes: a strict return policy (a 15% restocking fee).",
    "reasons": [
      "the official store of Example",
      "prices in line with major retailers (24 items compared)"
    ],
    "buyer_notes": [
      "a strict return policy (a 15% restocking fee)"
    ],
    "facts": {
      "kind": "shop",
      "platform": null,
      "role": "brand",
      "company": "Example Inc",
      "country": "US",
      "selling_since": null,
      "website_registered": "2015-04",
      "website": "example.com",
      "market": null,
      "rating": {
        "band": "good",
        "stars": "4.5+",
        "ratings": "1,000+",
        "source": "review sites"
      },
      "prices_vs_major_retailers": {
        "items_compared": 24,
        "typical_difference_pct": 0
      },
      "returns": {
        "accepted": "yes",
        "window_days": 30,
        "restocking_fee_pct": 15,
        "refund_to": null
      },
      "official_store_of": [
        "Example"
      ],
      "own_brands": null,
      "monthly_visits": "10,000-99,999",
      "products": 180,
      "risk_findings": []
    }
  }
}
```

##How to read the result

• -All seller fields are inside result in REST, including result.summary. Unlike vet_price, there is no separate top-level summary for this endpoint.
• -status tells you whether an assessment was produced: found, ambiguous or not_found. An unresolved identity is neither a positive nor a negative seller assessment.
• -trust_level may be trusted, reliable, limited, caution, risky or unknown. reliable means looks reliable; limited means little information vouches for the seller and is not itself a warning. unknown means insufficient information. Risk signals are not a legal finding of counterfeiting or proof of fraud.
• -Use seller_name and seller_url to confirm the identity. summary includes buyer considerations; reasons supports the assessment, buyer_notes adds purchase considerations, and facts holds available details. Null means unknown or unavailable.

##Empty results and errors

A successful request can return no candidates, missing information or an unavailable assessment. Check the result before recommending a product. For request failures, use the error code and message; retrying the same invalid input will not fix it.

• -[Error handling and retries](https://gaisho.co/docs/api#errors): HTTP statuses, structured errors, rate limits and quota responses.

##What to call next

• -[Get offer details](https://gaisho.co/docs/api/get_offer): Read a listing’s purchase URL, seller, price, coupon terms and stated product information.
• -[Compare purchase options](https://gaisho.co/docs/api/find_deals): Find offers for the same product, compatible alternatives, or models with specification upgrades and downgrades.

• -[Use this tool through MCP](https://gaisho.co/docs/mcp/vet_seller): The same capability through the other connection.
• -[REST API conventions](https://gaisho.co/docs/api): Authentication, response envelopes and request handling.