# BasketWatch > Irish grocery price intelligence for Aldi, Tesco, SuperValu, Dunnes Stores and Lidl: the products each chain lists online, with shelf prices and promotions, checked every morning, since May 2026 (Lidl since 17 October 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. We collect prices every morning, Irish time, and check Tesco and SuperValu again later in the morning. Every row carries the date of the snapshot it belongs to; filled or repaired rows are listed on our Data notes page (https://basketwatchireland.com/data-notes). ## What an agent can do here Query the catalogue and price history over HTTP or through the hosted MCP server, and pay for it without a human. Access is metered per record returned at EUR 0.001 per record, prepaid as credits valid for 30 days from purchase. 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=` 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 `, and the response carries a funded API key and its credit balance. Purchase terms, also returned on the discovery response and every 402 challenge body (`seller`, `terms_url`, `terms_version`, `buyer`, `credit_lifetime_days`, `refunds`): - Terms of Service: https://basketwatchireland.com/terms - Business customers only. Paying this challenge accepts the Terms of Service at terms_url on behalf of the business the agent acts for. - Credits are valid for 30 days from purchase. - Unused credits can be refunded within 14 days of purchase: email info@basketwatchireland.com. 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 AI assistant or MCP client BasketWatch runs a hosted Model Context Protocol server (Streamable HTTP) at: `https://basketwatchireland.com/mcp` - `compare_prices` (where a product is cheapest) and `status` work without an account. - Every other tool needs a BasketWatch account. Sign-in is OAuth 2.1 with Dynamic Client Registration and PKCE (S256): calling one of those tools without a token returns `401` with a `WWW-Authenticate` challenge whose `resource_metadata` points to `https://basketwatchireland.com/.well-known/oauth-protected-resource`. The person signs in with their email address and a 6-digit code; no API key is pasted anywhere. - A client that cannot sign in, or an agent that bought its own key over MPP, can connect with the key in the address instead: `https://basketwatchireland.com/mcp/`. - In ChatGPT it is added as a plugin (developer mode), and in Claude as a connector. Tools, all read-only: `compare_prices`, `price_basket` (a shopping list or receipt priced at all five stores), `price_basket_over_time` (the same basket on an earlier date), `price_movements` (a category's price moves between two dates), `find_products` (ingredient, nutrition, alcohol, offer and country of origin filters, e.g. Irish honey or Irish sirloin steaks; free-from filters also honour each retailer's "may contain" allergy advice), `get_product_details`, `get_price_history`, `search_products`, `compare_price_across_stores`, `lookup_barcode`, `get_promotions`, `recent_price_changes`, `newly_added_products`, `removed_products`, `list_products`, `check_credits`, `status`. One credit per record returned, from the same balance as the HTTP API. A client that only runs local servers can reach the hosted connector through a bridge such as `npx mcp-remote https://basketwatchireland.com/mcp/`. ## Endpoints - `GET /api/products` and `GET /api/{store}/products`: catalogue with current shelf price, unit price, pack size, promotion and barcode, and the retailer's own shelf every level down (`shelf_path`, e.g. Fresh Food > Yoghurts > Kefir > Kefir Drinks); `?category=` matches part of the department name or a whole level of the shelf - `GET /api/barcode/{code}` and `GET /api/barcodes?codes=`: look a GTIN, EAN or UPC barcode up across Aldi, Tesco, SuperValu, Dunnes and Lidl, up to 100 codes per call, with optional `fields=ingredients,nutrition,origin`; 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, what expires when (`expiring`, `next_expiry`) and ledger `store` is one of `tesco`, `supervalu`, `dunnes`, `lidl`. Aldi is the unprefixed set: `/api/products`, `/api/changes`. Lidl Plus prices (Lidl's member scheme) are member prices, in `clubcard_price` like Tesco Clubcard ones. Lidl prices are Lidl's online prices for its Tallaght store. 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): connect ChatGPT, Claude or any MCP client - [MCP connector](https://basketwatchireland.com/api-reference#mcp): the tools, sign-in, credits and limits - [Price Pulse](https://basketwatchireland.com/blog): published analysis built on the dataset - [Data notes](https://basketwatchireland.com/data-notes): how we correct mistakes, and the repairs that changed more than 100 price records - [Sources](https://basketwatchireland.com/sources): how BasketWatch uses sources, and how to raise a concern ## 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 the ones each retailer publishes online, on the date of the snapshot. Where we have filled a gap or repaired a record, our Data notes page says so (https://basketwatchireland.com/data-notes). In-store prices can differ. 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