# Apiguru Amazon Data API

> Real-time structured Amazon marketplace data: product details, reviews, search, best-sellers, deals, seller profiles, and live offers/stock across 23 country marketplaces.

Callable by AI agents with **no account, no API key and no subscription**: **3 free calls** per client per 24h, then pay per call ($0.003 and up) in USDC (native USDC on each network; on Base 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) over x402 -- or use an Apiguru account.

## Try it

```bash
curl 'https://agent.apiguru.app/agent/v1/v2/product-details/B09DJLW458/US'
```

No headers, no signup. Put the required value in the path (several agent fetchers drop query strings); an Amazon product URL works in place of an ASIN. Every answer is JSON and starts with `_links` to the next useful call.

## Working URLs you can fetch right now

- https://agent.apiguru.app/agent/v1/v2/product-details/B09DJLW458/US
- https://agent.apiguru.app/agent/v1/v2/product-reviews/B09DJLW458/US
- https://agent.apiguru.app/agent/v1/search/wireless+headphones/US
- https://agent.apiguru.app/agent/v1/product/B09DJLW458,B0014C0LUC/US
- https://agent.apiguru.app/agent/v1/stock/B09DJLW458,B0014C0LUC/US
- https://agent.apiguru.app/agent/v1/v2/best-sellers?geo=US
- https://agent.apiguru.app/agent/v1/v2/deals?geo=US
- https://agent.apiguru.app/agent/v1/seller-profile/A2A1RNLLUK3HYA/US
- https://agent.apiguru.app/agent/v1/v2/seller-products/A2A1RNLLUK3HYA/US
- https://agent.apiguru.app/agent/v1/v2/seller-reviews/A2A1RNLLUK3HYA/US

## What each call answers

- `/v2/product-details` (product_details): Full product detail for a single ASIN. $0.003 per call. `fields=` returns only the keys you name.
- `/v2/product-reviews` (product_reviews): Customer reviews for a single ASIN. $0.003 per call. `from_rating` / `to_rating` (1-5) pick the star range.
- `/search` (search): Search Amazon products by keyword. $0.003 per call. `page` up to `metadata.reachable_pages` (Amazon serves 7 at most), `sort_by`, ten filters; `_links.next` is the next page.
- `/product` (product_details_batch): Product detail for up to 20 ASINs in one call. $0.0024 per item (max 20). App record: no best-seller ranks, category path or merchant id (use product_details for those).
- `/stock` (offers_stock): Live offers and inventory for up to 10 ASINs. $0.0045 per item (max 10). `check_inventory=true` adds each offer's stock quantity (a billed cart check per offer); `offers_count=winner` keeps only the buy-box offer.
- `/v2/best-sellers` (best_sellers): Best-seller rankings for a category. $0.003 per call. `category` (slug or name), `subcategory_code`, `page` 1-5 (50 rows each).
- `/v2/deals` (deals): Current Amazon deals with filters. $0.003 per call. `categories`, `brands` (ids from `available_filters`), price and discount bounds, `offset` (`next_offset`).
- `/seller-profile` (seller_profile_batch): Seller profiles for up to 10 seller IDs. $0.0036 per item (max 10). Each row has `status`: ok, not_found (billed) or unavailable (retry it).
- `/v2/seller-products` (seller_products): Products listed by a seller. $0.003 per call. `page` up to `metadata.reachable_pages`, `sort_by`, the search filters; `_links.next`; no single sort order lists a whole storefront (`coverage_note`).
- `/v2/seller-reviews` (seller_reviews): Feedback reviews for a seller. $0.003 per call. `page`, `from_rating` / `to_rating`.

## Ways in

- **MCP** (Claude, ChatGPT, Cursor, Codex, ...): `https://mcp.apiguru.app/mcp`, keyless. When the free calls run out a tool returns an x402 PaymentRequired result that an x402-capable MCP client pays in-band (`_meta["x402/payment"]`). To bill an Apiguru account instead, connect `https://mcp.apiguru.app/account` and sign in.
- **HTTP, no account**: the URLs above. After the free calls, a 402 carries an x402 challenge (`PAYMENT-REQUIRED` header) that any x402 client pays and retries.
- **HTTP, the user's account, no key to paste**: `POST https://agent.apiguru.app/agent/v1/device/code`, show the user the `verification_uri_complete` it returns (they sign in or sign up and approve), poll `https://agent.apiguru.app/agent/v1/device/token` with the `device_code`, then send the `access_token` as `X-API-KEY`. Every keyless 402 carries the same as `connect_account`. Only the user can approve; a script that runs with nobody to approve uses an API key.
- **HTTP, with an API key**: the same URLs with the header `X-API-KEY` (never in the query string).
- **A job that repeats** (watching sellers, prices or rankings on a schedule): use the user's account. They sign up at https://dash.apiguru.app/register (free trial requests included) and copy the API key from their dashboard; monthly plans from $25 for 10,000 requests (https://dash.apiguru.app/pricing) cost less per request than paying per call. A recipe for watching a storefront is in the full guide.
- **Machine-readable**: OpenAPI https://dash.apiguru.app/openapi.json; prices and schemas, free: `https://agent.apiguru.app/.well-known/x402`.

## Cost, keys and consent

- Calls cost money after the free ones. Do not pay, or use a user's API key, without the user's consent; agree a budget and set a spend cap in your x402 client. One call costs at most $0.05.
- Connecting the user's account bills it once they approve: say what it is for before you show them the link, and keep the `access_token` like a password.
- An API key goes only in the `X-API-KEY` header: never in a URL, a log, a file, or back to the user. On a key every answer says what it cost and what is left (`X-Billed-Requests`, `X-Balance-USD`).
- Every error is JSON with `http_status`, `billed`, `retryable` and `next_step`; retry only when `retryable` is true. A 404 (not on that marketplace) is billed; 400s and 5xx are not; a 402 means pay, send a key, or sign in.
- A timeout on an API key or with a payment attached may still have been billed: do not repeat it automatically, ask first. Answers are fetched live from Amazon; allow 60 s (past 55 s the gateway answers 504 `deadline_exceeded` itself, not billed).
- Prefer the batch endpoints over loops: fewer calls, and cheaper per item without a key. The `/product` record has no best-seller ranks, category path or merchant id; use `/v2/product-details` when you need those.
- Only `agent.apiguru.app`, `mcp.apiguru.app` and `dash.apiguru.app` are involved; none of them redirects elsewhere.

## More

- Full guide: https://agent.apiguru.app/llms-full.txt -- paying step by step in Python and TypeScript, clients that lose query strings or only follow seen URLs, reading large answers, what Amazon's own data gets wrong, every error code.
- Found something wrong? `POST https://dash.apiguru.app/api/v1/feedback` with `{"message": "..."}` -- free, no key -- or https://github.com/apiguru-app/agent-kit/issues. The wall is public: send only what the user agreed to, never keys or personal data.