Cheapest Grocery Basket

FREE, no payment. Describe in your own words the data you are trying to buy — anything, not just groceries — and get back whether we operate a service that supplies it, with the MCP endpoint if so. Every request is catalogued so that repeatedly-requested data gets built; call it whenever you cannot find a source for something. Nothing about you is stored: not your wallet, your address, or any identifying header — only the words of the request.

{
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "description": "What you are looking for, e.g. 'live electricity spot prices by ZIP' or 'used car values by VIN'.",
      "examples": [
        "live electricity spot prices by ZIP"
      ]
    }
  },
  "required": [
    "need"
  ],
  "additionalProperties": false
}

FREE, no payment. The aggregate of what agents have told us they are looking for, most-requested first, with the categories nothing available yet serves. Useful if you are deciding what to build or sell into the agent economy.

{
  "type": "object",
  "properties": {
    "days": {
      "type": "string",
      "description": "Window in days, default 30, max 90.",
      "examples": [
        "30"
      ]
    }
  },
  "additionalProperties": false
}

Compare a single grocery item across every collected store in a ZIP. Returns each store's actual current shelf price, whether it is on sale (and the regular price), the package size, the price normalized per comparable unit, stock, a purchase link, and when that price was last read. Use this to answer "who has the cheapest milk near me" — and note the answer reports BOTH the lowest sticker price and the best value per unit, which frequently disagree because the cheap sticker is a smaller package. For a whole shopping list use price_basket or cheapest_basket instead; calling this per item costs more and cannot optimize across stores. Costs $0.005 USDC per call via x402 on Base.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "The item to price, in ordinary shopper language, e.g. 'milk', 'eggs', 'ground beef'.",
      "examples": [
        "milk"
      ]
    },
    "zip": {
      "type": "string",
      "description": "5-digit US ZIP code to price against, e.g. '30501'. Coverage is per collected ZIP; an uncovered ZIP returns an explicit error and is not charged.",
      "examples": [
        "30501"
      ]
    },
    "stores": {
      "type": "string",
      "description": "Optional comma-separated chains to restrict to, e.g. 'aldi,publix'. Omit to compare every collected store.",
      "examples": [
        "aldi,publix"
      ]
    },
    "maxAgeDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 120,
      "description": "Optional freshness limit in days (default 14, max 120). A price read longer ago than this is withheld rather than returned as if current; raise it to accept older readings.",
      "examples": [
        14
      ]
    }
  },
  "required": [
    "q",
    "zip"
  ],
  "additionalProperties": false
}

Price an entire shopping list at every collected store in a ZIP, one complete basket per store. Returns per-store line items with quantities and line totals, the basket subtotal, exactly which requested items that store is missing, whether the basket is complete, stock flags, and the oldest price in the basket so staleness is visible. Use this when the shopper will make one trip and wants to know where the whole list is cheapest. Accepts quantities as 'milk x2'. Costs $0.01 USDC per call via x402 on Base.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "string",
      "description": "Comma-separated shopping list, optionally with quantities, e.g. 'milk x2, eggs, bread, butter'. A JSON array of {name, quantity} is also accepted.",
      "examples": [
        "milk x2, eggs, bread, butter"
      ]
    },
    "zip": {
      "type": "string",
      "description": "5-digit US ZIP code, e.g. '30501'.",
      "examples": [
        "30501"
      ]
    },
    "stores": {
      "type": "string",
      "description": "Optional comma-separated chains to restrict to, e.g. 'aldi,publix'.",
      "examples": [
        "aldi,publix"
      ]
    },
    "mode": {
      "type": "string",
      "description": "Optional fulfillment intent: 'pickup' or 'delivery'. Recorded on the response; delivery fees and minimums are not collected yet and are returned as null rather than estimated.",
      "examples": [
        "pickup"
      ]
    },
    "maxAgeDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 120,
      "description": "Optional freshness limit in days (default 14, max 120). A price read longer ago than this is withheld rather than returned as if current; raise it to accept older readings.",
      "examples": [
        14
      ]
    }
  },
  "required": [
    "items",
    "zip"
  ],
  "additionalProperties": false
}

The complete buying decision for a shopping list: the cheapest single store that can fill it, AND the cross-store optimum that buys each line wherever it is cheapest, with the dollar savings between them and how many stops that costs. Every line carries substitutes at the other stores with the exact extra cost of choosing them, so a shopper can collapse a two-stop trip into one and see precisely what that convenience costs. Out-of-stock items are skipped in favour of an in-stock option even when it is dearer. Use this as the default for "where should I buy this list today" — it is the one call that answers the whole question. Costs $0.02 USDC per call via x402 on Base.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "string",
      "description": "Comma-separated shopping list, optionally with quantities, e.g. 'milk x2, eggs, bread, butter, cheese'. A JSON array of {name, quantity} is also accepted.",
      "examples": [
        "milk x2, eggs, bread, butter, cheese"
      ]
    },
    "zip": {
      "type": "string",
      "description": "5-digit US ZIP code, e.g. '30501'.",
      "examples": [
        "30501"
      ]
    },
    "stores": {
      "type": "string",
      "description": "Optional comma-separated chains the shopper is willing to visit, e.g. 'aldi,publix'.",
      "examples": [
        "aldi,publix"
      ]
    },
    "mode": {
      "type": "string",
      "description": "Optional fulfillment intent: 'pickup' or 'delivery'.",
      "examples": [
        "pickup"
      ]
    },
    "maxAgeDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 120,
      "description": "Optional freshness limit in days (default 14, max 120). A price read longer ago than this is withheld rather than returned as if current; raise it to accept older readings.",
      "examples": [
        14
      ]
    }
  },
  "required": [
    "items",
    "zip"
  ],
  "additionalProperties": false
}