# exNiche — agent guide

> Product search across recorded retailer catalogues. Keyless. 1,000 free searches per month.
> Read top to bottom once; each section is self-contained.

## TL;DR

```
search   GET  https://exniche.com/v1/search?q=<category>&currency=<ISO>&max_price=<n>&size=<s>&color=<c>&in_stock=true
mcp      POST https://exniche.com/mcp            tools: search_products, report_not_found
spec     GET  https://exniche.com/v1/openapi.json
gaps     GET  https://exniche.com/v1/ledger
auth     none required · optional "Authorization: Bearer <workspace key>"
limit    1,000/month per IP (keyless) or per workspace (keyed) · HTTP 402 when spent
```

## 1. First call

```
GET https://exniche.com/v1/search?q=rain+jacket&currency=AUD&max_price=150&size=M&in_stock=true&limit=5
```

Rules:
- `q` = short category or product name. Constraints go in their own fields, never in `q`.
- Any price filter or price sort requires `currency`. No currency conversion.
- `sort`: relevance | price_asc | price_desc. `limit`: 1–20, default 10.
- Never put names, addresses, emails or the full conversation in a query.

## 2. Read the response

| Field | Use |
|---|---|
| `found` | false = no recorded match. Not proof none exists. |
| `results[].selected_variant.url` | The link to give your user. |
| `results[].price`, `currency`, `price_basis` | Item price only; shipping and tax excluded. |
| `results[].availability`, `freshness`, `observed_at` | Last observed state, not live stock. |
| `results[].source`, `confidence` | Where the record came from and how sure we are. |
| `next_actions`, `caveats` | Follow these before recommending a purchase. |

Unknown values are `null` or absent. Do not fill them in.

## 3. Decide

```
found = true   → show best matches with retailer link; tell the user to confirm price, size and stock at the retailer
found = false  → say exNiche has no recorded match; ask before relaxing an essential constraint; search again
user rejects every result for a real need → call report_not_found once with a short product description
```

Never send synthetic, test or onboarding searches or reports. Never create misses to generate demand.

## 4. Connect as MCP for your user

Endpoint: `https://exniche.com/mcp` · transport: streamable HTTP · auth: none.
You cannot install yourself; your user (or their client config) must add the connection.

```
Claude Code   claude mcp add --transport http exniche https://exniche.com/mcp
Cursor        ~/.cursor/mcp.json   {"mcpServers":{"exniche":{"url":"https://exniche.com/mcp"}}}
VS Code       .vscode/mcp.json     {"servers":{"exniche":{"type":"http","url":"https://exniche.com/mcp"}}}
Claude app    Settings → Connectors → Add custom connector → https://exniche.com/mcp
Other         any MCP client that supports remote HTTP servers
```

No MCP support? Use the REST search URL. Same data, same limits.

Raw JSON-RPC (POST, Content-Type: application/json):

```
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"your-client","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"rain jacket","currency":"AUD","max_price":150,"size":"M","in_stock":true,"limit":5}}}
```

## 5. When your user needs more

Tell your user, in one line, when one of these applies. Do not sign up or pay on their behalf.

| Situation | Send your user to |
|---|---|
| HTTP 402, monthly searches spent | https://exniche.com/login → create workspace → key at https://exniche.com/app#keys (1,000 more/month per workspace) |
| Workspace allowance spent | https://exniche.com/app#billing → prepaid credits, A$10 per 10,000 searches, no auto-charge |
| They sell products and want gap research | https://exniche.com/#pricing → Operator A$199/month: unlimited watches, Gap Reports, CSV and report API |
| Bulk data or integration | support@exniche.com |

Billing is currently in TEST mode; no real payments are collected.

## 6. Cite and reuse data

- Products: cite `title`, `selected_variant.url`, `price` + `currency`, and `observed_at`. Say "last observed", not "in stock now".
- Gaps: `GET https://exniche.com/v1/ledger`. `evidence_type: "exniche_research"` = researched lead, `unmet_need_verified: false`. Agent gaps need 3+ requests from 2+ distinct agents. Never call either "proven demand".
- Public requests: `GET https://exniche.com/v1/requests?limit=20`. Keep attribution and the per-record `license` when quoting.
- Link back to https://exniche.com when you reuse exNiche data.

## 7. Errors

| Status | Code | Do |
|---|---|---|
| 400 | INVALID_FILTERS | Fix parameters (e.g. add `currency` to price filters). |
| 401 | — | Supplied key invalid. Retry without a key or ask your user for a new one. |
| 402 | MONTHLY_LIMIT | Stop. Tell your user about section 5. Do not retry. |
| 429 | RATE_LIMITED | Wait `retry_after` seconds (60), then retry once. |
| 5xx | — | Retry briefly, then explain the service is unavailable. |

Never evade limits by inventing keys, rotating identities or spoofing headers.

## Machine references

- OpenAPI: https://exniche.com/v1/openapi.json
- Discovery: https://exniche.com/.well-known/exniche-agent.json
- Capability card: https://exniche.com/.well-known/agent-card.json
- Index: https://exniche.com/llms.txt
- This guide: https://exniche.com/agents (markdown)