# Waltrack: agent guide

Waltrack tracks Walmart products: each product on the user's watchlist is checked on a schedule (every 5 minutes to 24 hours, depending on the plan), every check is kept as price history, and the user gets an email when the price drops, reaches a target or the product is back in stock. Human-readable documentation: https://www.waltrack.dev/docs

## Connect

- MCP endpoint (Streamable HTTP, stateless JSON): `https://www.waltrack.dev/api/mcp`
- Auth: OAuth for clients that support it (Claude, ChatGPT): add the URL, then sign in and allow access. Otherwise `Authorization: Bearer <API_KEY>`, or `?key=<API_KEY>` for clients that only accept a URL
- Get a key: https://www.waltrack.dev/app#api (one key per tool, revocable at any time)

Claude Code:

```bash
claude mcp add --transport http waltrack https://www.waltrack.dev/api/mcp --header "Authorization: Bearer <API_KEY>"
```

Any client that reads an `mcpServers` JSON config:

```json
{ "mcpServers": { "waltrack": { "url": "https://www.waltrack.dev/api/mcp", "headers": { "Authorization": "Bearer <API_KEY>" } } } }
```

## Tools

| Tool | Arguments | Returns |
| --- | --- | --- |
| `get_account` | none | plan, plan_name, credits, renews_at, products, product_limit, fastest_interval_minutes, monthly_credits, manage_url |
| `search_walmart` | `query`, `marketplace?` | results: item_id, title, image, price, currency, rating, reviews_count |
| `track_product` | `product`, `marketplace?`, `target_price?`, `interval_minutes?` | the tracked product: product_id, title, price, currency, lowest_price… |
| `list_products` | `item_id?`, `marketplace?`, `filter?`, `page?`, `limit?` | products (each with trend), total, page |
| `get_price_history` | `product_id`, `days?` | the product and history: price, in_stock, coupon, seller, checked_at |
| `get_item_history` | `item_id`, `marketplace?`, `days?` | item_id, marketplace, currency, lowest_price, highest_price, average_price, history: price, in_stock, coupon, seller, checked_at |
| `update_product` | `product_id`, `target_price?`, `interval_minutes?`, `alert_on_drop?`, `paused?` | the updated product |
| `check_product` | `product_id` | the product with its latest price |
| `untrack_product` | `product_id` | deleted, product_id |

## Recommended flow

1. The user names a product without an item ID: call `search_walmart` and confirm the right result with them.
2. Call `track_product` with the item ID (or the Walmart link). It checks the price right away and returns it. Only set `target_price` or `interval_minutes` when the user asks.
3. For "how has the price moved", call `get_price_history` on a tracked product, or `get_item_history` for any item ID, free and without tracking it. Prices are in the product's `currency`; `null` means there was no offer at that check.
4. Use `list_products` to answer questions about the whole watchlist, with `filter` for the usual ones: what dropped, what reached its target, what's out of stock or needs attention.

Each price check of a tracked product costs 1 credit; a product checked daily uses about 30 credits a month. The free plan tracks 50 products, checked daily (`interval_minutes` 1440). Accepted intervals: 5, 30, 60, 360, 720, 1440 minutes. Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business. When a tool fails, its text ends with the error code in parentheses, e.g. `(product_limit)`.

## Marketplaces

| Marketplace | Store | Country | Currency |
| --- | --- | --- | --- |
| `com` | walmart.com | United States | USD |

## Reading a product

Test these in order; the first match is the product's state (the app shows the same as a badge):

| State | When | Meaning |
| --- | --- | --- |
| Checking | `checking is true` | A check is due or running. Poll GET /products/{id} every few seconds, or pass wait. |
| Paused | `status is "paused"` | Not checked, not charged. PATCH paused: false to resume. |
| Confirm your email | `last_error is "email_not_verified"` | The free credits come with the email confirmation; checks start right after it. |
| Waiting for credits | `last_error is "insufficient_credits"` | The balance is empty; the check runs again by itself once credits are added (manage_url). |
| Not found on Walmart | `last_error is "product_not_found"` | No page for this item ID on Walmart (refunded). |
| Retrying soon | `last_error is "store_unavailable"` | Walmart couldn't be read (refunded). Retried automatically; nothing to do. |
| Queued | `last_checked_at is null` | Added, first check not done yet. |
| Out of stock | `in_stock is false` | Checked, but no offer: price is null. With alert_on_drop, the owner gets an email when it's back. |
| In stock | `in_stock is true` | Checked, with an offer at price (in currency). |

## Watchlist filters (`filter` on list_products)

| filter | Products |
| --- | --- |
| `all` | Every tracked product (default). |
| `drops` | Cheaper now than when the product was added. |
| `target` | At or below its target price. |
| `out_of_stock` | No offer at the last check. |
| `attention` | The last check didn't go through (last_error is set): no credits, not found or Walmart unavailable. |
| `paused` | Paused by you: not checked, not charged. |

## last_error on a product

| Code | Meaning |
| --- | --- |
| `email_not_verified` | The account's email isn't confirmed yet, so it has no credits; the check runs as soon as it is. |
| `insufficient_credits` | The last check was skipped for lack of credits; it's retried every 6 hours. |
| `store_unavailable` | Walmart couldn't be read at the last check (refunded); retried within 30 minutes. |
| `product_not_found` | The item ID has no page on Walmart (refunded). |

## Errors

| HTTP | Code | When |
| --- | --- | --- |
| 400 | `invalid_product` | product is neither a Walmart item ID (the number at the end of a walmart.com/ip/ link) nor a Walmart product link, or item_id isn't a Walmart item ID (the number at the end of a walmart.com/ip/ link). |
| 400 | `unsupported_marketplace` | The link is from a Walmart site other than walmart.com. |
| 400 | `invalid_option` | A setting isn't valid: marketplace (com), filter, interval_minutes (5, 30, 60, 360, 720, 1440), target_price, alert_on_drop or paused. Also when the body isn't a JSON object, a required argument is missing, or the product to check is paused. |
| 401 | `unauthorized` | The API key is missing, revoked or invalid. |
| 402 | `insufficient_credits` | Reading Walmart now costs 1 credit and the balance is empty. |
| 402 | `email_not_verified` | The account's email isn't confirmed yet, so it has no credits to read Walmart with. |
| 403 | `paid_option` | Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business. |
| 403 | `product_limit` | The account tracks as many products as its plan allows (50 on the free plan). |
| 404 | `not_found` | No tracked product with this id on your account, or no such endpoint. |
| 404 | `product_not_found` | Walmart has no product for this item ID. Refunded. |
| 405 | `method_not_allowed` | The endpoint doesn't take this HTTP method; the Allow header lists the ones it does. |
| 429 | `rate_limited` | More than 30 searches or 600 history reads in an hour, too many reads of Walmart at once, or too many different products read today: 200 a day on the free plan, 1,000 with a credit pack, then 1,000 with Starter, 3,000 with Pro, 10,000 with Business. Histories and new watchlist entries count, once per product; your watchlist and the products already read today stay available. Retry later, or after midnight UTC for the daily limit. |
| 500 | `generic` | Unexpected error on our side. Retry in a moment. |
| 502 | `store_unavailable` | Walmart couldn't be read right now (GET /search). Nothing is charged; retry in a moment. |

Searches are limited to 30 per hour per account, and `get_item_history` to 600.

## REST API

The same key works with the REST API: `https://www.waltrack.dev/api/v1`. OpenAPI schema: https://www.waltrack.dev/openapi.json
