demandex

Demandex — E-commerce Demand Intelligence for AI Agents

API at https://api.demandex.dev. Demandex is the index of what people want next: it classifies Reddit complaint and intent posts across ~70 communities into demand signals (replacement-part hunts, unmet needs, willingness-to-pay, repeat failures), clusters them into scored opportunity cards (0-100 = frequency × intensity × willingness-to-pay) with verbatim evidence and permalinks, and answers ad-hoc demand verdicts for any query. Strictly pay-per-call via x402 — no accounts, no API keys, no bundles. Compute-first / settle-after: you are never charged for an error or an empty result.

Physical products only. Evidence is quoted from public Reddit posts with provenance (subreddit, upvotes, permalink). Informational only — not a guarantee of any business outcome.

Check the active payment mode any time at GET /health (live|mock).

Free endpoints (no auth, no payment)

Use these to learn the response shapes before paying.

curl https://api.demandex.dev/v1/categories
curl https://api.demandex.dev/v1/sample/opportunity

The free sample is the fastest way to learn the full card shape: it returns the same fields a paid /v1/opportunity returns, so an agent can wire up parsing for free, then spend on live cards.

Paid endpoints (x402 V2, USDC on Base, per-call)

Each paid call is a flat price per call, paid via x402. Compute-first / settle-after — you are not charged on any error, and never for an empty result (a still-warming index returns a no-charge 503 corpus_warming).

Prices are USD, settled as USDC (6 decimals). The verdict shape (both gauges): { query, verdictScore (0-100), demandTemperature (cold|warm|hot), rationale, topEvidence[] (≤5, each { quote, permalink, upvotes }), relatedOpportunities[] (≤5, each { slug, score }), cache (hit|miss), fetchedAt }. A zero-match query is a real cold verdict (chargeable), not an error.

Gauge request bodies

# Cached demand verdict ($0.03)
curl -X POST https://api.demandex.dev/v1/gauge \
  -H "Content-Type: application/json" \
  -d '{"query":"sony xm5 replacement headband","category":"headphones"}'

# Live-research demand verdict ($0.10) — same body, fresh Reddit search at request time
curl -X POST https://api.demandex.dev/v1/gauge/live \
  -H "Content-Type: application/json" \
  -d '{"query":"sony xm5 replacement headband"}'

query is required (3..200 chars); category is optional (scopes the corpus match). The body is read first, falling back to ?query=.

Paying (x402) — first call

Every paid route follows the standard x402 challenge → pay → retry flow. Try every response shape for free first via /v1/categories and /v1/sample/opportunity.

# 1) Call a paid route with no payment → 402 challenge (you are not charged)
curl -s "https://api.demandex.dev/v1/opportunities/trending"
# → { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453",
#     "asset": "USDC", "price": "$0.01", "payTo": "…" }, … ] }

# 2) Sign an x402 'exact' USDC authorization for the Base accepts[] rail, then retry.
#    Standard @x402 V2 clients send PAYMENT-SIGNATURE; legacy clients send X-PAYMENT.
curl -s "https://api.demandex.dev/v1/opportunities/trending" -H "PAYMENT-SIGNATURE: "
# → 200 { …, "charged": true }

MCP server (demandex-mcp)

Agents can use the demandex-mcp npm package — an MCP server wrapping api.demandex.dev that handles the x402 payment flow for you. It exposes the 2 free endpoints plus the 5 paid routes as MCP tools. Register it with an MCP client (e.g. Claude) via npx:

{
  "mcpServers": {
    "demandex": {
      "command": "npx",
      "args": ["-y", "demandex-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x…",
        "DEMANDEX_API_URL": "https://api.demandex.dev"
      }
    }
  }
}

EVM_PRIVATE_KEY (falls back to PRIVATE_KEY) funds the paid tools with USDC on Base. DEMANDEX_API_URL is optional and defaults to https://api.demandex.dev.

Free-tier mode: without a private key the server still starts, exposing only the 2 free tools (get_categories, get_sample_opportunity) — enough to learn every response shape before you fund a wallet. Set EVM_PRIVATE_KEY to unlock the 5 paid tools.

Free-funnel guidance

Start on the free plane to learn Demandex for zero cost, then spend only where it pays:

1. GET /v1/categories — poll this to see which categories have live opportunity cards and how fresh they are (lastUpdated, topScore). Cheap change-detection.
2. GET /v1/sample/opportunity — wire up your full-card parser here for free; it is the same shape as the paid /v1/opportunity.
3. Then buy: /v1/opportunities/trending ($0.01) to browse, /v1/opportunities?category= ($0.02) to drill into a category, /v1/opportunity?slug= ($0.05) for full evidence, /v1/brief ($0.25) for a whole-job market brief in one call, and /v1/gauge ($0.03) / /v1/gauge/live ($0.10) for ad-hoc verdicts.

Machine discovery

Errors & caveats

• 400 — bad params (missing/unknown category; missing/ambiguous id/slug; query outside 3..200 chars). You were NOT charged.
• 402 — payment required / verification or settlement failed (you were NOT charged).
• 404 — requested opportunity not found (you were NOT charged).
• 503 corpus_warming — the index is still building; no cards to return yet (you were NOT charged).
• 503 — LLM synthesis temporarily unavailable on a gauge call (you were NOT charged).
• 504 — /v1/gauge/live exceeded its 45s research budget (you were NOT charged).

Disclaimer: Demand intelligence aggregated from public Reddit posts; physical products only; informational, not professional or business advice; provided as-is. Evidence reflects the mined corpus at fetch time. Terms: https://api.demandex.dev/terms.txt