# ebay-browse — eBay Browse API (gated)

Official Buy → Browse API, live listings only (no sold data: Marketplace Insights is limited release).

- Auth: OAuth2 client credentials (`EBAY_CLIENT_ID` = App ID, `EBAY_CLIENT_SECRET` = Cert ID; optional
  `EBAY_ENV=sandbox`). Token cached in-process (`_g10-lib cachedToken`), refreshed 60 s before expiry.
- `GET /buy/browse/v1/item_summary/search?q&category_ids&filter&sort=newlyListed&limit=200&offset` per
  (query × marketplace × page); header `X-EBAY-C-MARKETPLACE-ID` ∈ EBAY_US/CA/GB/DE/FR/AU; offset+limit ≤ 10,000.
- Normalised `listing`: native marketplace currency, listingType from `buyingOptions`, seller username +
  feedback, shipping cost, item location, `listedAt`/`endsAt`, `bidCount`, grade from title, identifiers
  `ebay_item_id`, `ebay_legacy_item_id`, `ebay_epid`.
- `lookup()` resolves `ebay.*/itm/<legacyId>` through `get_item_by_legacy_id`.
- Fixtures are built from the official OpenAPI contract (buy_browse_v1 v1.20.4) field definitions, not
  live captures — see `note` in each fixture.

Credentials: https://developer.ebay.com → My Account → Application Keys (production keyset) → Buy API
access application.