# BasketWatch

> Irish grocery price intelligence. Every product, every shelf price, every promotion, from the public websites of Aldi, Tesco, SuperValu and Dunnes Stores, captured daily since May 2026.

BasketWatch is a data API. It answers questions about what Irish groceries cost: current shelf prices, daily price movements, live promotions, loyalty prices, unit prices, pack sizes and cross-retailer product matching by barcode.

Roughly 50,000 products are priced every morning, Irish time, and two chains are re-checked later the same day to catch promotions that activate after the overnight run. Every row carries the date it was captured.

## What an agent can do here

Query the catalogue and price history directly over HTTP, and pay for it without a human. Access is metered per record returned at EUR 0.001 per record, prepaid as credits. There is no subscription. The minimum top-up is EUR 49.99, whoever is buying.

## Paying as an agent

BasketWatch accepts machine payments over the Machine Payments Protocol (MPP), settling by card through Stripe Shared Payment Tokens.

- Discovery: `GET https://basketwatchireland.com/api/credits/mpp`
- Purchase: `POST https://basketwatchireland.com/api/credits/mpp/buy?pack=<eur_cents>`

Request the purchase endpoint with no credential and it returns `402 Payment Required` with a `WWW-Authenticate: Payment` challenge naming the `stripe` method and `charge` intent. Grant a shared payment token scoped to the `networkId` in the challenge, retry with `Authorization: Payment <base64url(credential)>`, and the response carries a funded API key and its credit balance.

Send that key as `X-API-Key` on every subsequent request. Each response reports `X-Credits-Charged` and `X-Credits-Remaining`, so an agent can meter itself as it goes. `GET /api/credits` returns the balance and ledger and is free.

An agent with a USDC wallet can also pay over x402 at `/api/credits/x402` where that door is enabled.

## Using it from an MCP client

`pip install basketwatch-mcp` gives a Model Context Protocol server that exposes this data as
tools to Claude, Cursor and any other MCP client. It runs locally against your own API key, so
nothing is proxied and your credits meter exactly as on a direct request. With no key configured
each tool returns a live 50-row sample.

## Endpoints

- `GET /api/products` and `GET /api/{store}/products` — catalogue with current shelf price, unit price, pack size, promotion and barcode
- `GET /api/barcode/{code}` and `GET /api/barcodes?codes=`: look a GTIN, EAN or UPC barcode up across all four retailers, up to 100 codes per call, with optional `fields=ingredients,nutrition`; one credit per barcode found however many retailers list it, codes with no match are free
- `GET /api/changes` and `GET /api/{store}/changes` — daily price movements, with shelf moves, promotions and loyalty prices kept as separate signals rather than blended
- `GET /api/{store}/promotions` — live promotions with their published validity windows
- `GET /api/status` — coverage and freshness per retailer, free and unauthenticated
- `GET /api/credits` — credit balance and ledger

`store` is one of `tesco`, `supervalu`, `dunnes`. Aldi is the unprefixed set: `/api/products`, `/api/changes`.

Anonymous callers get a capped sample of 50 rows per request so the shape of the data can be inspected before buying. It is the same 50 rows on every request: the cap cannot be paginated past, and search, category and sort parameters do not move the sample, so the catalogue cannot be walked a page at a time. Single-product lookup is likewise limited to those sampled products without a key.

## Documentation

- [API reference](https://basketwatchireland.com/api-reference): endpoints, parameters, response shapes, sample payloads
- [Pricing](https://basketwatchireland.com/pricing): credit packs and the per-record rate
- [Methodology](https://basketwatchireland.com/methodology): how prices are captured, verified and corrected
- [Agent access](https://basketwatchireland.com/agent-access): MCP-compatible access for analyst workflows
- [Price Pulse](https://basketwatchireland.com/blog): published analysis built on the dataset

## Good questions to ask this API

- Which supermarket is cheapest for a specific product today, and by how much
- What changed price at a named retailer yesterday, and whether it was a shelf move or a promotion
- What a product has cost every day since May 2026
- Which products are on promotion right now at a named retailer, and when each offer ends
- How own-label compares with the branded equivalent per kilo or litre

## Limits

Prices are as displayed on the retailers' own websites on the stated date. In-store prices can differ. Lidl is not tracked. Data is provided for analysis; redistributing it publicly or reselling it requires a separate licence, so contact info@basketwatchireland.com first.

## Contact

info@basketwatchireland.com