# StockX API — live resale market data for sneakers, streetwear, and electronics (lowest ask, highest bid, last sale, sales volume, price premium, volatility, per-size variant pricing) from stockx.com

> full product by `url` OR `url_key`/`id`/`uuid`: title/brand/model/sku/category/colorway/retail_price/release_date/image + market{lowest_ask,highest_bid,number_of_asks/bids,last_sale,sales_last_72h,last_sale_change_pct/value,avg_price_72h/90d/annual,sales_count_*,price_premium=(last_sale-retail)/retail, volatility=CV-of-recent-sales, ask_service_levels{standard/express_*: count,lowest_ask,processing_fee,delivery}} + per-size variants[]{size,lowest_ask,highest_bid,last_sale}. The market-data moat. `currency` (USD/EUR/GBP/…) + `market` (US/GB/DE/…) optional.
> ReefAPI engine `stockx` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/stockx/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /stockx/v1/product_detail — 2 credits
full product by `url` OR `url_key`/`id`/`uuid`: title/brand/model/sku/category/colorway/retail_price/release_date/image + market{lowest_ask,highest_bid,number_of_asks/bids,last_sale,sales_last_72h,last_sale_change_pct/value,avg_price_72h/90d/annual,sales_count_*,price_premium=(last_sale-retail)/retail, volatility=CV-of-recent-sales, ask_service_levels{standard/express_*: count,lowest_ask,processing_fee,delivery}} + per-size variants[]{size,lowest_ask,highest_bid,last_sale}. The market-data moat. `currency` (USD/EUR/GBP/…) + `market` (US/GB/DE/…) optional.

**Parameters:**
- `url_key` (string, optional) — Product slug from the StockX product URL (stockx.com/<url_key>) — copy it from search results. Internal id/uuid also accepted. Provide url_key OR url.
- `url` (string, optional) — Full StockX product URL — alternative to url_key.
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]
- `market` (enum, optional, default "US") — Marketplace region (affects asks/bids and service levels). [one of: US, GB, DE, FR, IT, ES, NL, JP, AU, CA, KR, HK, SG, CH, MX, NZ, SE, DK, NO, PL, CN, TW, TH]

**Returns:** product{title, brand, model, sku, category, colorway, retail_price, release_date, image, market{lowest_ask, highest_bid, last_sale, sales_last_72h, avg_price_72h/90d/annual, price_premium, volatility, ask_service_levels}, variants[]{size, lowest_ask, highest_bid, last_sale}}

**Example request body:**
```json
{
  "url_key": "air-jordan-4-retro-bred-reimagined"
}
```

### POST /stockx/v1/search — 1 credit
product search → results[]{id,url_key,url,title,brand,sku,category,image,lowest_ask,highest_bid,last_sale} + page_info{page,limit,total}. Resolves url_keys for product_detail. Optional facet filters: `brand` (e.g. Jordan), `gender` (men/women/…), `category` (sneakers/apparel/…) + `sort` (most-active/featured/release_date/lowest_ask). `page` (40/page) + `currency`/`market` optional.

**Parameters:**
- `query` (string, required) — What to search for (product keywords).
- `page` (integer, optional, default 1) — Page number (40 results per page).
- `brand` (string, optional) — Filter results to a brand (StockX facet value, e.g. Jordan, Nike, adidas, New Balance, Supreme).
- `gender` (enum, optional) — Filter results by gender facet. [one of: men, women, youth, infant]
- `category` (enum, optional) — StockX vertical to browse (grid of that whole category). [one of: sneakers, apparel, electronics, collectibles, accessories]
- `sort` (enum, optional) — Result ordering for browse/trending grids. [one of: most-active, featured, release_date, lowest_ask]
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]
- `market` (enum, optional, default "US") — Marketplace region (affects asks/bids and service levels). [one of: US, GB, DE, FR, IT, ES, NL, JP, AU, CA, KR, HK, SG, CH, MX, NZ, SE, DK, NO, PL, CN, TW, TH]

**Returns:** results[]{id, url_key, url, title, brand, sku, category, image, lowest_ask, highest_bid, last_sale} + page_info{page, limit, total} (meta.pagination for paging)

**Example request body:**
```json
{
  "query": "jordan 1"
}
```

### POST /stockx/v1/recent_sales — 1 credit
recent transaction feed by `url`/`url_key`/`id` → sales[]{amount,created_at} (most recent first) + product ref. Best-effort market-history. `currency`/`market` optional.

**Parameters:**
- `url_key` (string, optional) — Product slug from the StockX product URL (stockx.com/<url_key>) — copy it from search results. Internal id/uuid also accepted. Provide url_key OR url.
- `url` (string, optional) — Full StockX product URL — alternative to url_key.
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]
- `market` (enum, optional, default "US") — Marketplace region (affects asks/bids and service levels). [one of: US, GB, DE, FR, IT, ES, NL, JP, AU, CA, KR, HK, SG, CH, MX, NZ, SE, DK, NO, PL, CN, TW, TH]

**Returns:** sales[]{amount, created_at} (most recent first) + product reference

**Example request body:**
```json
{
  "url_key": "air-jordan-4-retro-bred-reimagined"
}
```

### POST /stockx/v1/suggest — 1 credit
autocomplete query suggestions for `query` (QuerySuggestion text; falls back to search-derived titles if the suggest op drifts).

**Parameters:**
- `query` (string, required) — Partial search text to complete.

**Returns:** suggestions[] (plain strings)

**Example request body:**
```json
{
  "query": "jordan"
}
```

### POST /stockx/v1/price_history — 3 credits
historical price time-series for a product, aggregated from the deep sales feed → series[]{date,count,avg,min,max,last} (oldest→newest) + summary{points,sales_sampled,min,max,avg,first_date,last_date,window_complete}. `window` (30d/90d/180d/365d/all) bounds lookback; `bucket` (day/week/month) sets granularity; optional `size` for per-size history. The #1 resale-trader ask. `currency` optional.

**Parameters:**
- `url_key` (string, optional) — Product slug from the StockX product URL (stockx.com/<url_key>) — copy it from search results. Internal id/uuid also accepted. Provide url_key OR url.
- `url` (string, optional) — Full StockX product URL — alternative to url_key.
- `window` (enum, optional, default "90d") — How far back the price series reaches. [one of: 30d, 90d, 180d, 365d, all]
- `bucket` (enum, optional, default "day") — Time-bucket granularity for each series point. [one of: day, week, month]
- `size` (string, optional) — Optional shoe/apparel size for per-size price history (must match a product variant size, e.g. 10, 10.5, M).
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]

**Returns:** series[]{date, count, avg, min, max, last} + summary{points, sales_sampled, window, bucket, min, max, avg, first_date, last_date, window_complete} + product

**Example request body:**
```json
{
  "url_key": "air-jordan-4-retro-bred-reimagined",
  "window": "90d",
  "bucket": "day"
}
```

### POST /stockx/v1/sales_history — 1 credit
deep paginated transaction log → sales[]{amount,created_at,cursor} (newest first) + page_info{cursor,has_more,total,limit,returned} + product. Far deeper than recent_sales (StockX exposes the full ledger, e.g. 60k+ sales). Cursor-paginate with `cursor`; optional `size` filters to one variant. `limit` ≤ 50 (StockX page cap). `currency` optional.

**Parameters:**
- `url_key` (string, optional) — Product slug from the StockX product URL (stockx.com/<url_key>) — copy it from search results. Internal id/uuid also accepted. Provide url_key OR url.
- `url` (string, optional) — Full StockX product URL — alternative to url_key.
- `cursor` (string, optional) — Pagination cursor from a previous page_info.cursor (omit for the first/newest page).
- `limit` (integer, optional, default 50) — Rows per page (StockX caps at 50).
- `size` (string, optional) — Optional size for one variant's transaction log.
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]

**Returns:** sales[]{amount, created_at, cursor} + page_info{cursor, has_more, total, limit, returned} + product (+ variant when `size` given)

**Example request body:**
```json
{
  "url_key": "air-jordan-4-retro-bred-reimagined",
  "limit": 50
}
```

### POST /stockx/v1/browse — 1 credit
category/vertical grids + sort + facet filters → results[]{id,url_key,url,title,brand,sku,category,image,lowest_ask,highest_bid,last_sale} + page_info{page,limit,total}. Needs at least one of `category` (sneakers/apparel/electronics/collectibles/accessories), `query`, or a facet filter (`brand`/`gender`). `sort` (most-active/featured/release_date/lowest_ask) + `page` (40/page) optional. The catalog-discovery surface.

**Parameters:**
- `category` (enum, optional) — StockX vertical to browse (grid of that whole category). [one of: sneakers, apparel, electronics, collectibles, accessories]
- `query` (string, optional) — Optional keyword to combine with category/filters.
- `brand` (string, optional) — Filter results to a brand (StockX facet value, e.g. Jordan, Nike, adidas, New Balance, Supreme).
- `gender` (enum, optional) — Filter results by gender facet. [one of: men, women, youth, infant]
- `sort` (enum, optional) — Result ordering for browse/trending grids. [one of: most-active, featured, release_date, lowest_ask]
- `page` (integer, optional, default 1) — Page number (40 results per page).
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]
- `market` (enum, optional, default "US") — Marketplace region (affects asks/bids and service levels). [one of: US, GB, DE, FR, IT, ES, NL, JP, AU, CA, KR, HK, SG, CH, MX, NZ, SE, DK, NO, PL, CN, TW, TH]

**Returns:** results[]{id, url_key, url, title, brand, sku, category, image, lowest_ask, highest_bid, last_sale} + page_info{page, limit, total}

**Example request body:**
```json
{
  "category": "sneakers",
  "sort": "most-active"
}
```

### POST /stockx/v1/trending — 1 credit
movers / most-active products (global or within a `category`) → results[] (same card shape as browse) + page_info. Defaults `sort`=most-active. Optional `category`, `brand`, `gender`, `page`. Surfaces what's trading right now.

**Parameters:**
- `category` (enum, optional) — StockX vertical to browse (grid of that whole category). [one of: sneakers, apparel, electronics, collectibles, accessories]
- `brand` (string, optional) — Filter results to a brand (StockX facet value, e.g. Jordan, Nike, adidas, New Balance, Supreme).
- `gender` (enum, optional) — Filter results by gender facet. [one of: men, women, youth, infant]
- `sort` (enum, optional) — Result ordering for browse/trending grids. [one of: most-active, featured, release_date, lowest_ask]
- `page` (integer, optional, default 1) — Page number (40 results per page).
- `currency` (enum, optional, default "USD") — Currency for all prices. [one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, KRW, MXN, NZD, SGD, SEK, DKK, NOK, PLN, CNY, TWD, THB]
- `market` (enum, optional, default "US") — Marketplace region (affects asks/bids and service levels). [one of: US, GB, DE, FR, IT, ES, NL, JP, AU, CA, KR, HK, SG, CH, MX, NZ, SE, DK, NO, PL, CN, TW, TH]

**Returns:** results[]{id, url_key, url, title, brand, sku, category, image, lowest_ask, highest_bid, last_sale} + page_info{page, limit, total}

## More
- Try it live, no code: https://reefapi.com/playground?engine=stockx
- Human docs page: https://reefapi.com/docs/stockx
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt