# demandex-mcp

MCP server for **[Demandex](https://demandex.dev)** — pay-per-call **e-commerce demand
intelligence** for AI agents. Demandex mines Reddit complaint/intent posts across ~70
communities into scored **opportunity cards** with verbatim evidence and permalinks, and
answers ad-hoc **demand verdicts** for any physical-product query. Pay **per call** with USDC
on **Base** via **x402** — no signup, no accounts, no API keys.

- **2 free tools** — no wallet, no API key.
- **5 paid tools** — flat per-call USD prices, settled in USDC on **Base Mainnet** via x402.

Try before you pay: the free `get_sample_opportunity` tool returns a real, fixed opportunity
card in the same full shape as the paid `get_opportunity`, so you can learn the exact response
shape first.

---

## Quick start

### Free tier (no wallet)

```json
{
  "mcpServers": {
    "demandex": {
      "command": "npx",
      "args": ["-y", "demandex-mcp"]
    }
  }
}
```

You get `get_categories` and `get_sample_opportunity`.

### Paid tier (with wallet)

Add an EVM wallet private key (0x-prefixed) that holds USDC on **Base Mainnet**:

```json
{
  "mcpServers": {
    "demandex": {
      "command": "npx",
      "args": ["-y", "demandex-mcp"],
      "env": { "EVM_PRIVATE_KEY": "0x..." }
    }
  }
}
```

The paid tools then settle each call automatically.

### Install snippets

Claude Code:

```bash
claude mcp add demandex -- npx -y demandex-mcp
# with a wallet:
claude mcp add demandex --env EVM_PRIVATE_KEY=0x... -- npx -y demandex-mcp
```

Claude Desktop / Cursor: add the JSON block above to your MCP config
(`claude_desktop_config.json` or `.cursor/mcp.json`).

---

## Tools

### Free tools

| Tool | Endpoint | Description |
| --- | --- | --- |
| `get_categories` | `GET /v1/categories` | Category index with `opportunityCount`, `topScore`, `lastUpdated` per category. |
| `get_sample_opportunity` | `GET /v1/sample/opportunity` | Real, fixed sample opportunity card showing the full paid card shape. |

### Paid tools

| Tool | Endpoint | Price (USD) | Description |
| --- | --- | --- | --- |
| `get_trending_opportunities` | `GET /v1/opportunities/trending` | **$0.01** | Top 20 trending cards as teasers (`id, slug, title, category, score, signalCount, lastSeen`). |
| `get_opportunities` | `GET /v1/opportunities` | **$0.02** | Up to 50 cards in a `category` (teaser + `summary`). Optional `minScore` (0-100). |
| `get_opportunity` | `GET /v1/opportunity` | **$0.05** | One FULL card by `id` or `slug` (exactly one) — all score components, productAngle, summary, verbatim `evidence[]`. |
| `gauge_demand` | `POST /v1/gauge` | **$0.03** | Demand verdict for a product `query` (3–200 chars), cached 7 days, corpus-only. Optional `category`. |
| `gauge_demand_live` | `POST /v1/gauge/live` | **$0.10** | Demand verdict with a LIVE Reddit search at request time (~45s budget). Same body as `gauge_demand`. |

Prices are flat per call — **no bundles, no entitlements**. The verdict shape (both gauges):
`{ query, verdictScore (0-100), demandTemperature (cold|warm|hot), rationale, topEvidence[],
relatedOpportunities[], cache, fetchedAt }`.

---

## How payments work (x402)

Demandex speaks the [x402](https://x402.org) `exact` scheme. The API's 402 advertises a
**Base** (USDC, EIP-3009) rail; this MCP settles on **Base**:

1. The MCP requests a paid endpoint. With no payment, the API replies **HTTP 402** with the
   accepted terms.
2. If `EVM_PRIVATE_KEY` is set, the MCP settles the call via the standard `@x402/fetch` V2
   client and retries. If no key is set, the MCP returns the **402 price terms** so you can
   see the cost without paying.
3. The API returns the data plus a `charged: true` marker.

**Compute-first, settle-after:** Demandex computes the full answer **before** charging, so you
are never billed for an error or an empty result (a still-warming index returns a no-charge
`503 corpus_warming`).

No accounts, no API keys — just a wallet with USDC on **Base Mainnet**. Physical products only.

---

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `EVM_PRIVATE_KEY` | No | 0x-prefixed wallet key with **USDC on Base Mainnet**. Required to pay the 5 paid tools on a live API. `PRIVATE_KEY` is accepted as a fallback. Free tools work without it; without a key the paid tools surface the 402 price terms. |
| `DEMANDEX_API_URL` | No | Override the API base URL (default `https://api.demandex.dev`). |

---

## Disclaimer

Demandex provides **informational** e-commerce demand intelligence aggregated from public
Reddit posts; physical products only; not professional or business advice; provided as-is. See
<https://api.demandex.dev/terms.txt>.

Docs for agents: <https://api.demandex.dev/llms.txt> ·
full: <https://api.demandex.dev/llms-full.txt>

---

## License

MIT © jcislo