# exNiche agent guide

exNiche finds products people ask for and can't buy. Each gap pools real asks (community
posts, AI agent searches, store searches), is checked against live retail and scored
go / maybe / no-go. A go verdict means "worth a closer look", never proof that people will buy.

Use `/agents` on this site's origin for the complete current REST and MCP guide,
`/v1/openapi.json` for the contract, and `/llms.txt` for discovery links.

## Start with check_demand

MCP HTTP JSON-RPC endpoint: `/mcp`. Discover live tool schemas with `tools/list`.
Tools: `check_demand` (start here), `list_gaps`, `get_gap`, `get_dossier`,
`search_products`, `report_not_found`, `get_setup_and_upgrade_links`.

`check_demand` takes a short product idea, returns matching gaps at summary level and
records the ask as one AI agent search. Ask the user before `get_dossier` unlocks a dossier.

REST (relative to this site's origin):

```text
/v1/gaps?verdict=go,maybe&sort=score&limit=20
/v1/gaps/{slug}?detail=full
/v1/search?q=keyboard&max_price=150&currency=USD&in_stock=true&sort=relevance&limit=10
```

## Credits

| Call | Credits |
|---|---|
| `search_products` / `GET /v1/search` | 1 |
| `check_demand` | 1 |
| `report_not_found` | 0 |
| `list_gaps` / `GET /v1/gaps` (summary) | 1 per call |
| `list_gaps` (detail=full) | 1 + 10 per scored row |
| `get_gap` (detail=full) | 100 (summary: 1) |
| `get_dossier`, not yet unlocked | 19,000, unlocks for the account |
| `get_dossier`, already unlocked | 0 |

No account or API key is needed: keyless callers get 1,000 free credits per calendar month
per IP. A workspace key adds 1,000 free credits a month, then prepaid credits
(A$10 = 10,000, never expire). HTTP 402 (MCP: `isError` with code `MONTHLY_LIMIT` or
`CREDITS_EXHAUSTED`) carries `upgrade_url` and `human_message`: show both to the user.
Nothing is charged automatically. No x402.

## Licence

Every gap record carries `licence`, `attribution` and `source_label`. exNiche data: use
with attribution to exniche.com; quoted asks keep their source licence (Stack Exchange:
CC BY-SA 4.0, link and author).

## Product search

Keep `q` a short category/name; provide constraints separately. No currency conversion.
Read `found`, `results`, `next_actions` and `caveats`. Unknown values are null or absent.
Check current price, size, color, availability and shipping on the retailer page.
This API searches recorded catalogue data; it does not place orders.

An agent cannot install itself as a ChatGPT integration: a supported client connection
or user configuration step is required.

Only report genuine unsatisfied shopping requests. A reported miss is an agent assertion,
not proof that no product exists or verified human demand. Never create synthetic misses
or asks to test onboarding. Omit personal information from queries.