{
  "openapi": "3.1.0",
  "info": {
    "title": "Cheapest Grocery Basket",
    "version": "1.0.3",
    "contact": {
      "email": "corrections@mcpscores.com"
    },
    "description": "Grocery basket optimization for agents: where to buy a whole shopping list today at real local store prices, with package sizes normalized to a common unit. Pay per call in USDC on Base via x402."
  },
  "x-agentcash-guidance": {
    "llmsTxtUrl": "https://grocery-basket.bowling-anthony.workers.dev/llms.txt"
  },
  "servers": [
    {
      "url": "https://grocery-basket.bowling-anthony.workers.dev"
    }
  ],
  "paths": {
    "/find": {
      "get": {
        "tags": [
          "grocery",
          "shopping"
        ],
        "summary": "find product",
        "description": "Compare one grocery item across every collected store in a ZIP: actual shelf price, sale price and regular price, package size, price normalized per comparable unit, stock, purchase link, and when the price was last read.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.005"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Item to price, in shopper language",
            "schema": {
              "type": "string"
            },
            "example": "milk"
          },
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "5-digit US ZIP code",
            "schema": {
              "type": "string"
            },
            "example": "30501"
          },
          {
            "name": "stores",
            "in": "query",
            "required": false,
            "description": "Optional comma-separated chains to restrict to",
            "schema": {
              "type": "string"
            },
            "example": "aldi,publix"
          },
          {
            "name": "maxAgeDays",
            "in": "query",
            "required": false,
            "description": "Freshness window for prices (default 14)",
            "schema": {
              "type": "integer"
            },
            "example": 14
          }
        ],
        "responses": {
          "200": {
            "description": "Paid data (returned only after the x402 payment settles).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment challenge with an `accepts` array; retry with a base64 X-PAYMENT header.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "ZIP or product not covered. Returned honestly and never billed."
          }
        }
      }
    },
    "/basket": {
      "get": {
        "tags": [
          "grocery",
          "shopping"
        ],
        "summary": "price basket",
        "description": "Price a whole shopping list at every collected store in a ZIP: per-store line items, subtotals, which items each store is missing or is out of, and the oldest price in the basket.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "items",
            "in": "query",
            "required": true,
            "description": "Comma-separated list, quantities allowed as 'milk x2'",
            "schema": {
              "type": "string"
            },
            "example": "milk,eggs,bread,butter"
          },
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "5-digit US ZIP code",
            "schema": {
              "type": "string"
            },
            "example": "30501"
          },
          {
            "name": "stores",
            "in": "query",
            "required": false,
            "description": "Optional comma-separated chains",
            "schema": {
              "type": "string"
            },
            "example": "aldi,publix"
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Fulfillment intent: pickup or delivery",
            "schema": {
              "type": "string"
            },
            "example": "pickup"
          }
        ],
        "responses": {
          "200": {
            "description": "Paid data (returned only after the x402 payment settles).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment challenge with an `accepts` array; retry with a base64 X-PAYMENT header.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "ZIP or product not covered. Returned honestly and never billed."
          }
        }
      }
    },
    "/cheapest": {
      "get": {
        "tags": [
          "grocery",
          "shopping"
        ],
        "summary": "cheapest basket",
        "description": "The whole buying decision: cheapest single store that can fill the list, the cross-store optimum that buys each line where it is cheapest, the dollar savings and stops between them, and per-line substitutes with their exact extra cost.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.02"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "items",
            "in": "query",
            "required": true,
            "description": "Comma-separated list, quantities allowed as 'milk x2'",
            "schema": {
              "type": "string"
            },
            "example": "milk,eggs,bread,butter,cheese"
          },
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "5-digit US ZIP code",
            "schema": {
              "type": "string"
            },
            "example": "30501"
          },
          {
            "name": "stores",
            "in": "query",
            "required": false,
            "description": "Optional comma-separated chains the shopper will visit",
            "schema": {
              "type": "string"
            },
            "example": "aldi,publix"
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Fulfillment intent: pickup or delivery",
            "schema": {
              "type": "string"
            },
            "example": "pickup"
          }
        ],
        "responses": {
          "200": {
            "description": "Paid data (returned only after the x402 payment settles).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment challenge with an `accepts` array; retry with a base64 X-PAYMENT header.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "ZIP or product not covered. Returned honestly and never billed."
          }
        }
      }
    }
  }
}