# Demandex API — E-commerce demand intelligence for AI agents — the index of what people want next. Per-call, no signup. (v0.1.0)

> Demandex is the index of what people want next — a pay-per-call e-commerce demand gauge for AI
> agents. It mines Reddit complaint/intent posts into scored opportunity cards with verbatim
> evidence, and answers ad-hoc demand verdicts for any product query. Try the free category index
> (GET /v1/categories) and the free honest sample (GET /v1/sample/opportunity) to see the shapes
> before you pay. Physical products only.

## Base URL
- API: https://api.demandex.dev
- This document: https://api.demandex.dev/llms.txt  ·  Extended: https://api.demandex.dev/llms-full.txt
- Discovery (JSON): https://api.demandex.dev/discovery
- OpenAPI 3.1: https://api.demandex.dev/openapi.json
- x402 manifest: https://api.demandex.dev/.well-known/x402
- Agent card (A2A): https://api.demandex.dev/.well-known/agent-card.json
- Terms: https://api.demandex.dev/terms.txt

## Free endpoints (no auth, no payment)

| Method | Path | Description |
|--------|------|-------------|
| GET | /v1/categories | Free, no payment. Returns the category index — every active category with its opportunity count, top opportunity score, and last-updated time. A cheap change-detection funnel an agent can poll to learn which categories to buy into. Shape: { categories: [{ slug, opportunityCount, topScore, lastUpdated }], generatedAt }. (rate limit: 30/min) |
| GET | /v1/sample/opportunity | Free, no payment. Returns one REAL, fixed sample opportunity card in the SAME full shape as the paid GET /v1/opportunity — all score components, productAngle, summary, and verbatim evidence — plus { sample: true, note, cardAsOf }. It is a stable teaching sample (real data) so an agent can learn the exact card shape before paying. Returns 503 corpus_warming only while the index is empty (no cards mined yet). (rate limit: 10/min) |

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

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| GET | /v1/opportunities/trending | $0.01 | Paid ($0.01 USDC via x402). Returns the top 20 active opportunity cards by score as TEASERS — { id, slug, title, category, score, signalCount, lastSeen } only. No evidence and no productAngle (buy GET /v1/opportunity for the full card). While the index is still warming and no active cards exist yet, you get a no-charge 503 corpus_warming (never an empty charged list) — poll the free GET /v1/categories to see when cards go live. Compute-first / settle-after — you are not charged on any error. Response carries fetchedAt. |
| GET | /v1/opportunities | $0.02 | Paid ($0.02 USDC via x402). Returns up to 50 active opportunity cards in a category, each as a teaser ({ id, slug, title, category, score, signalCount, lastSeen }) plus its summary. Requires ?category=; ?minScore= optionally filters. A missing or unknown category returns a no-charge 400 that lists the valid categories; a valid category with no active cards yet (index still warming) returns a no-charge 503 corpus_warming instead of an empty charged list. Compute-first / settle-after — you are not charged on any error. Response carries fetchedAt. |
| GET | /v1/opportunity | $0.05 | Paid ($0.05 USDC via x402). Returns one full opportunity card by ?id= or ?slug= (exactly one required, else a no-charge 400): all score components (freqScore, intensityScore, wtpScore), productAngle, summary, evidence[] (verbatim quotes with subreddit, upvotes, permalink), builderMomentum, firstSeen, lastSeen, signalCount, distinctAuthors. Compute-first / settle-after — you are not charged when the id/slug is missing, ambiguous, or not found. Response carries fetchedAt. |
| POST | /v1/gauge | $0.03 | Paid ($0.03 USDC via x402). POST { "query": "...", "category"?: "..." } to get a demand verdict for any physical-product query. Answers are cached 7 days by normalized query; on a cache miss Demandex matches the query against the mined corpus (signals and cards by keyword) and runs one LLM synthesis call. query must be 3..200 chars. Reads the JSON body first, falling back to ?query=. Verdict shape: { 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. If the LLM is unavailable you get a 503 and are not charged. Compute-first / settle-after. |
| POST | /v1/gauge/live | $0.1 | Paid ($0.10 USDC via x402). Same body as /v1/gauge — POST { "query": "...", "category"?: "..." } (query 3..200 chars; body-first, ?query= fallback). Combines the mined corpus with a LIVE Reddit search run at request time (up to 50 posts, subreddits unrestricted) and one LLM synthesis call. Total compute budget is 45 seconds; on timeout you get a 504 and are not charged. Returns the same verdict shape as /v1/gauge (cache is always miss). A zero-match, empty-search query is a real cold verdict (chargeable), not an error. If the LLM is unavailable you get a 503 and are not charged. Compute-first / settle-after. |

## How to pay (x402)
Each paid call answers a 402 challenge; sign an x402 `exact` USDC authorization for one advertised rail (Base) and retry. Standard @x402 V2 clients send the `PAYMENT-SIGNATURE` header; legacy clients send `X-PAYMENT`. Prices are USD, settled as USDC (6 decimals).

## Links
- Docs: https://api.demandex.dev/llms.txt
- Full: https://api.demandex.dev/llms-full.txt
- OpenAPI: https://api.demandex.dev/openapi.json
- Discovery: https://api.demandex.dev/discovery
- Agent card: https://api.demandex.dev/.well-known/agent-card.json
- Website: https://demandex.dev

## How Demandex works
Signal mining → clustering → scoring. Demandex ingests posts from ~70 communities and classifies each into one of eight demand patterns (repeat failure, replacement hunt, unmet need, willingness-to-pay, alternative seeking, workaround, recommendation request, frustration). Related signals are clustered into opportunity cards, each scored 0-100 as frequency × intensity × willingness-to-pay. Cards carry verbatim evidence quotes with their subreddit, upvote counts, and permalinks so every claim is traceable to a public post. The corpus refreshes every ~30 minutes; each priced response carries a fetchedAt timestamp. Demandex is informational only and covers physical products exclusively — it is not a guarantee of any business outcome.