# Apiguru Amazon Data API

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

Apiguru is callable by AI agents with **no account, no API key and no subscription**. This is live now, not a plan.

## Quickstart

```bash
curl 'https://agent.apiguru.app/agent/v1/v2/product-details?asin=B09DJLW458&geo=US'
```

No headers. No signup. That returns live Amazon data.

## What it costs and how you pay

- **3 free calls** per client per 24h, so you can check this API fits your task before spending anything.
- After that: HTTP **402** with a `PAYMENT-REQUIRED` header stating exactly what to pay. Any x402-capable HTTP client settles it and retries automatically.
- Paid in **USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)** on **Base mainnet (eip155:8453)**.
- Watch `X-Free-Probes-Remaining` and `X-Price-Next-Call` on every response to know where you stand before you get a 402.

Free probes are counted by client IP. IPv6 addresses are bucketed to their /64, so every address in one allocation shares a single budget. Forged proxy headers do not create new budgets.

## Paying

You need two things: an x402 client library, and an EVM wallet key whose address holds a little **USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)** on **Base mainnet (eip155:8453)**. Nothing else: no account here, no ETH for gas (the facilitator submits the transfer), no minimum deposit. One call costs about a cent; `X-Price-Next-Call` on every response is the exact figure.

How a paid call works: your first request gets `402` with a `PAYMENT-REQUIRED` header (base64 JSON: the `accepts` list names the scheme `exact`, the network, the asset, the receiving address and the amount). The client signs an EIP-3009 authorization for that amount and retries the same request with a `PAYMENT-SIGNATURE` header (`X-PAYMENT`, the v1 name, is accepted too). The gateway verifies the signature, serves the request, and settles on-chain only after a billable answer (2xx, or the 404 that means the item does not exist). If the failure was ours you see `X-Payment-Status: not-settled` and pay nothing. The libraries below do all of this on a plain 402; you just wrap your HTTP client.

Python (`pip install "x402[evm,httpx]" eth-account`):

```python
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

client = x402Client().set_spend_controls({"max_amount_per_payment": "$1"})
register_exact_evm_client(client, EthAccountSigner(Account.from_key(PRIVATE_KEY)))
async with x402HttpxClient(client) as http:
    r = await http.get("https://agent.apiguru.app/agent/v1/v2/product-details", params={"asin": "B09DJLW458"})
    print(r.status_code, r.headers.get("X-Payment-Status"), r.json()["data"]["product_title"])
```

TypeScript / Node (`npm i @x402/fetch @x402/evm viem`):

```ts
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
client.setSpendControls({ maxAmountPerPayment: "$1" });
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(PRIVATE_KEY)));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const r = await fetchWithPayment("https://agent.apiguru.app/agent/v1/v2/product-details?asin=B09DJLW458");
```

Keep the spend control: it caps what one 402 can take from the wallet. Batch endpoints bill per item (up to 20 items, so up to $0.16 in one call); check `X-Price-Next-Call` or `/.well-known/x402` before raising the cap.

No wallet and no way to get one? An API key from https://dash.apiguru.app/register comes with free trial calls and bills a normal account instead; MCP clients such as claude.ai and ChatGPT sign in through https://mcp.apiguru.app/account and never touch x402.

## Free forever, never metered

Use these to plan a job at zero cost before committing to a paid call:

- `https://agent.apiguru.app/health`
- `https://agent.apiguru.app/llms.txt`
- `https://agent.apiguru.app/.well-known/x402`
- `https://agent.apiguru.app/feedback`

`/.well-known/x402` lists every endpoint with its price and JSON Schema, so you can decide what to call and what it will cost without spending a probe. The MCP server exposes the same thing as a free `list_capabilities` tool that answers locally with no network call.

## Interfaces

- [MCP server](https://mcp.apiguru.app/mcp): streamable HTTP, keyless; also installable locally (`uvx apiguru-mcp`).
- [MCP server, signed in](https://mcp.apiguru.app/account): OAuth 2.1 for claude.ai, Claude Desktop and ChatGPT connectors; bills your Apiguru account.
- [OpenAPI spec](https://dash.apiguru.app/api/v1/openapi.json): full machine-readable schema for all 10 endpoints.
- [Keyed REST API](https://dash.apiguru.app/api/v1): for existing customers, `X-API-KEY` header.
- [Docs](https://dash.apiguru.app/docs): human documentation.

## Endpoints

- **`GET /v2/product-details`** — Full product detail for a single ASIN. Required: `asin`. Price: $0.01 per call.
- **`GET /v2/product-reviews`** — Customer reviews for a single ASIN. Required: `asin`. Price: $0.01 per call.
- **`GET /search`** — Search Amazon products by keyword. Required: `query`. Price: $0.01 per call.
- **`GET /product`** — Product detail for up to 20 ASINs in one call. Required: `asins`. Price: $0.008 per item (max 20).
- **`GET /stock`** — Live offers and inventory for up to 10 ASINs. Required: `asins`. Price: $0.015 per item (max 10).
- **`GET /v2/best-sellers`** — Best-seller rankings for a category. Required: none. Price: $0.01 per call.
- **`GET /v2/deals`** — Current Amazon deals with filters. Required: none. Price: $0.01 per call.
- **`GET /seller-profile`** — Seller profiles for up to 10 seller IDs. Required: `seller_ids`. Price: $0.012 per item (max 10).
- **`GET /v2/seller-products`** — Products listed by a seller. Required: `seller_id`. Price: $0.01 per call.
- **`GET /v2/seller-reviews`** — Feedback reviews for a seller. Required: `seller_id`. Price: $0.01 per call.

## Conventions

- **Marketplaces** (20): US, CA, DE, MX, UK, FR, IT, ES, AU, BR, IN, JP, NL, AE, PL, SA, SG, SE, TR, BE. Pass as `geo`, chosen from the user's request or the Amazon domain they mention (amazon.de -> DE). The API assumes `US` only when the parameter is omitted; do not rely on that.
- **ASIN format**: `^[A-Z0-9]{10}$`. Uppercase only. Lowercase ASINs are rejected with 400 - normalise before calling.
- **Seller ID format**: `^[A-Za-z0-9]{13,15}$`.
- **Sample ASIN for testing**: `B09DJLW458`.

## Error semantics

These matter for cost control — some errors bill and some do not:

- **400** — Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.
- **401** — Missing or invalid API key on the keyed path.
- **402** — Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.
- **403** — Account disabled, or no active subscription plan.
- **413** — Too many items in a batch request.
- **429** — Per-second rate limit exceeded for the plan. Back off and retry.
- **404** — The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.
- **503** — Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.
- **500** — Internal error. NOT billed.

**Retry policy:** Retry 503 and 429 with backoff. Never retry 400/404 - the input itself is the problem.

## Telling us what is broken

This API has been fixed more than once because an agent said what was wrong with it. If a field is empty, mistyped, welded together or simply missing, say so:

- **Preferred - GitHub issues:** https://github.com/apiguru-app/agent-kit/issues. An issue can hold a conversation; you get a reply on the thread.
- **No GitHub account? The wall:** `POST https://dash.apiguru.app/api/v1/feedback` with `{"message": "...", "category": "bug|wish|praise|question|other", "endpoint": "/search", "agent": "your-name/1.0"}`. No key, no signup, never billed.
- **Over MCP:** the free `send_feedback` tool does the same thing.
- **Read what others wrote:** https://dash.apiguru.app/feedback