# 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| seller | string | Required | Seller ID, marketplace account key, seller page, store domain, name or product page. Cannot be empty; up to 2000 characters. |

## 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.

| Field | Type | Description |
| --- | --- | --- |
| tool | string | The tool called: vet_seller. |
| result.status | string | Whether the seller could be identified and assessed. |
| result.seller_key / seller_name / seller_url | string \| null | Seller identity and link, when available. |
| result.trust_level / trust_label | string \| null | Trust assessment and its readable label. |
| result.summary | string \| null | Seller assessment. |
| result.reasons / buyer_notes | string[] \| null | Supporting reasons and buyer considerations. |
| result.facts | object \| null | Available information supporting the assessment. |
| result.message | string \| null | Additional information when an assessment is unavailable. |
| result.facts.kind / platform / role | string \| null | Seller type (first_party, marketplace_seller, shop or web), its marketplace and its role, when known. |
| result.facts.company / country / website | string \| null | Business identity and the store’s website domain (for example example.com, without https://), when known. |
| result.facts.market | string \| null | The country a store’s website is for, such as CA or GB, when its address names one; null for a US or generic address. |
| result.facts.official_store_of / own_brands | string[] \| null | Brands it is the official or authorized store of, and brands it appears to sell as its own. |
| result.facts.prices_vs_major_retailers | object \| null | items_compared and typical_difference_pct against major retailers for the same items. |
| result.facts.monthly_visits / products | string \| number \| null | Estimated monthly visits to its website, as a band, and the number of products listed on it. |
| result.facts.selling_since / website_registered | string \| null | Available start or registration month, formatted YYYY-MM. |
| result.facts.rating | object \| null | Seller-rating information and its source; this is not a product rating. |
| result.facts.returns | object \| null | Known return terms, such as window_days or restocking_fee_pct. |
| result.facts.risk_findings | string[] | Reported risk findings; an empty list is not a guarantee about an order. |

## 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

| Situation | How to handle it |
| --- | --- |
| ambiguous | Read message, then supply a specific seller identity or domain. A message that begins “No store goes by the name” lists stores whose names only contain the words; they are unlikely to be the intended seller, so ask for the store’s website. |
| not_found | There is no assessment. Do not interpret this as trusted or risky. |
| found with trust_level unknown | The seller was identified but there is insufficient information for a stronger assessment. |
| The returned seller is not the intended seller | Use the exact marketplace seller page or account key and repeat the check. |

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.