Docs

One backend, two doors: connect over MCP for agents, or call the REST API directly. Same auth, same data.

1 · Get a key

Grab a free so_live_ key from the dashboard. Pass it as a Bearer token on every call.

2 · Connect over MCP

Add a remote MCP connector (Claude Desktop / ChatGPT / Cursor):

{
  "mcpServers": {
    "selloracle": {
      "url": "https://selloracle.com/mcp",
      "headers": { "Authorization": "Bearer so_live_YOUR_KEY" }
    }
  }
}

Then just ask: "Score the niche 'minimalist wedding invitation' on Etsy." Your agent calls get_niche_score and answers with real data.

3 · Or call REST

curl https://selloracle.com/api/v1/niche/score?keyword=minimalist+wedding+invitation \
  -H "Authorization: Bearer so_live_YOUR_KEY"

# → { "success": true, "data": { "blueOceanScore": 72, "level": "blue", ... } }

POST tools take a JSON body:

curl -X POST https://selloracle.com/api/v1/profit-calc \
  -H "Authorization: Bearer so_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price": 24, "shipping": 0, "offsiteAds": false }'

Auth, rate limits & quotas

· Header on every call: Authorization: Bearer so_live_…
· Keys are stateless HMAC tokens, stable per account. Counting is per key (cloud agents rotate IPs).
· Response headers: X-RateLimit-Remaining (free tier), X-Credits-Remaining (paid).

Plan	Daily cap	Monthly credits	Burst
Free	100 calls/day (A-tier only)	—	5 req/s
Starter	no daily cap	10,000	10 req/s
Pro	no daily cap	50,000	20 req/s
Scale	no daily cap	300,000	50 req/s

Bursts above your tier return 429; back off and retry. Need higher throughput? Scale or a custom plan.

Data & freshness

· Source — derived from Etsy's public Open API. We expose aggregated, computed signals (scores, demand, competition) — not a resale of raw Etsy rows.
· A-tier (data) — niche aggregates & Blue Ocean scores are pre-computed and refreshed weekly. Each response is consistent for a given week.
· B-tier (live) — hits Etsy at call time, so it reflects the marketplace right now.
· Coverage — all categories; 45K+ listings and 1,400+ shops at full import.
· Live service status & the refresh log live on the status page.

Quick client (no SDK needed)

Official TypeScript & Python SDKs are on the way. Until then it's a one-liner — here's a tiny typed wrapper you can paste in:

// selloracle.ts
const KEY = process.env.NICHEGRID_KEY!;
const BASE = "https://selloracle.com/api/v1";

export async function call(path: string, opts: RequestInit = {}) {
  const res = await fetch(BASE + path, {
    ...opts,
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", ...opts.headers },
  });
  if (!res.ok) throw new Error(`SellOracle ${res.status}: ${await res.text()}`);
  return res.json();
}

// usage
const { data } = await call("/niche/score?keyword=minimalist+wedding+invitation");
console.log(data.blueOceanScore); // 72

Python:

# selloracle.py
import os, requests
KEY = os.environ["NICHEGRID_KEY"]
BASE = "https://selloracle.com/api/v1"

def call(path, method="GET", json=None):
    r = requests.request(method, BASE + path,
        headers={"Authorization": f"Bearer {KEY}"}, json=json)
    r.raise_for_status()
    return r.json()

data = call("/niche/score?keyword=minimalist+wedding+invitation")["data"]
print(data["blueOceanScore"])  # 72

Error codes

Status	Meaning
401	Missing or invalid API key
402	Out of credits (paid tiers)
403	Tier locked — upgrade your plan
404	Unknown endpoint or no data for input
429	Free daily limit reached

Tool reference

get_niche_score Data · 1cr · GET /api/v1/niche/score

Blue Ocean Score (0–100) for one keyword, with the four underlying signals (demand, saturation, concentration, freshness) plus avg price, views, favorites, and shop count. The computed conclusion — not raw listings.

keyword (string, required) — The search term to score, e.g. "boho wedding invitation".

get_niche_report Data · 2cr · GET /api/v1/niche/report

A multi-section deep report for one keyword: verdict, demand & competition read, price band, top shops, and a recommended angle. Everything an agent needs to make a go/no-go call in one call.

keyword (string, required) — The niche keyword to report on.

find_blue_ocean Data · 1cr · GET /api/v1/blue-ocean

Discover low-competition, high-demand niches in a category, ranked by Blue Ocean Score. Free tier returns the top 5; the full ranked list is the core paid asset.

category (string) — Optional category filter, e.g. "wedding", "home", "jewelry". Omit to scan all categories.
limit (number) — How many niches to return (free tier capped at 5).

search_keywords Data · 1cr · GET /api/v1/keywords

Keyword lookup with cached stats (total results, avg price, score). The free hook that gets an agent onto the grid.

q (string, required) — Substring to match against the keyword index.

get_best_sellers Data · 1cr · GET /api/v1/best-sellers

Top-selling listings in a category, by favorites/sales signal.

category (string) — Category to rank within. Omit for an overall ranking.

get_top_shops Data · 1cr · GET /api/v1/shops/top

Leading shops in a category by sales, with sales/review/follower stats.

category (string) — Category to rank shops within.

profit_calculator Data · 1cr · POST /api/v1/profit-calc

Full Etsy fee breakdown and net profit for a sale (listing, transaction, payment-processing, and optional offsite-ads fees). Pure math — no data lookup.

price (number, required) — Item sale price (USD).
cost (number) — Your cost of goods (USD).
shipping (number) — Shipping charged to buyer (USD).
offsiteAds (boolean) — Apply the 15% Offsite Ads fee?

live_keyword_lookup Live · 2cr · GET /api/v1/keywords/live

Real-time Etsy search volume + competition for a keyword (bypasses the cache).

keyword (string, required) — Keyword to look up live.

rank_check Live · 3cr · GET /api/v1/rank-check

Scan the top 100 results for a keyword and report where a given listing ranks.

listingId (string, required) — Etsy listing id.
keyword (string, required) — Keyword to check rank for.

listing_audit Live · 2cr · GET /api/v1/listing/audit

SEO audit of a single live listing (title, tags, attributes).

url (string, required) — Etsy listing URL.

shop_analyzer Live · 2cr · GET /api/v1/shop/analyze

Real-time deep-dive on a shop's catalog and performance.

shop (string, required) — Etsy shop name.

ai_listing_optimizer AI · 10cr · POST /api/v1/ai/listing-optimizer

Generate an optimized title + 13 tags from the top-ranking listings for a keyword.

keyword (string, required) — Target keyword.

ai_niche_validator AI · 10cr · POST /api/v1/ai/niche-validator

An AI go/no-go verdict on a product idea, grounded in real niche data.

idea (string, required) — The product idea to validate.

ai_product_spec AI · 10cr · POST /api/v1/ai/product-spec

Generate a full product specification for a niche.

keyword (string, required) — Niche keyword.

ai_review_insights AI · 10cr · POST /api/v1/ai/review-insights

Mine a shop's real reviews for what buyers love, complain about, and the concrete fixes.