{
  "openapi": "3.1.0",
  "info": {
    "title": "DealPulse API",
    "description": "Global deal intelligence API. AI-synthesized best deals, price history, coupon discovery, cashback optimization, subscription audits, credit card stack analysis, grocery savings, student discounts, and flash sale tracking. Covers 50+ major retailers globally with real-time price comparison and Amazon affiliate links. Rakuten cashback, Slickdeals, CamelCamelCamel price tracker, and retailer coupon affiliates included. All endpoints support any language via ?lang=. Pricing: $0.05\u2013$0.10 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://dealpulse-weld.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://dealpulse-weld.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Omit to receive a 402 with payment requirements. Sign and retry to receive data."
      }
    }
  },
  "paths": {
    "/api/deals/store": {
      "get": {
        "summary": "Store coupon codes and promotions",
        "description": "Returns current promo codes, sales, cashback, and offers for any store or restaurant. Each deal includes a confidence rating and recency signal. Includes cashback app opportunities and a best_play recommendation.",
        "operationId": "dealsStore",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "store",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store or restaurant name (e.g. Target, Chilis, Nike)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Store deals with confidence-rated coupon codes"
          },
          "402": {
            "description": "Payment required \u2014 x402 PAYMENT-REQUIRED header contains payment details"
          }
        },
        "x-price-usd": 0.05,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Best active store promotions \u2014 chain with /api/deals/item for combined product+store deal"
      }
    },
    "/api/deals/item": {
      "get": {
        "summary": "Best deal on a specific product",
        "description": "Finds the best current way to save on a specific product \u2014 combining sale prices, coupon codes, cashback, price matching, and bundle opportunities. Ranked by estimated savings. Includes buy_now_or_wait recommendation.",
        "operationId": "dealsItem",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product name or description (e.g. 65 inch TV, AirPods Pro)"
          },
          {
            "name": "budget",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Maximum budget in USD"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked deals with buy/wait recommendation"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Best deal on a specific product \u2014 Amazon + cashback links auto-appended; start here for any product query"
      }
    },
    "/api/deals/compare": {
      "get": {
        "summary": "Live price comparison across retailers",
        "description": "Compares current prices for a specific item across major retailers (Amazon, Walmart, Target, Best Buy, etc.) with shipping, return policy, and active promotions. Returns best_overall recommendation and price history context.",
        "operationId": "dealsCompare",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Specific product name (e.g. Samsung 65 inch QN90B, Dyson V15)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Retailer price comparison with best_overall pick"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Price comparison across retailers \u2014 chain after /api/deals/item to expand search; CamelCamelCamel tracker included"
      }
    },
    "/api/deals/event": {
      "get": {
        "summary": "Sale event intelligence",
        "description": "Best deals for major sale events (Black Friday, Prime Day, Cyber Monday, etc.) filtered by category. Each deal rated genuinely_good / decent / hype / skip. Includes categories to target and avoid, plus a shopping strategy.",
        "operationId": "dealsEvent",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "event",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sale event name (e.g. black-friday, prime-day, cyber-monday)"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product category filter (e.g. electronics, appliances, clothing)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Event deal intelligence with genuine vs. hype ratings"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.05,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Seasonal sale events (Black Friday, Prime Day, Cyber Monday) \u2014 forecast best deal timing"
      }
    },
    "/api/deals/subscriptions": {
      "get": {
        "summary": "Subscription audit \u2014 cancel vs. keep analysis with cost savings",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Subscription audit \u2014 cancel vs. keep analysis; Rocket subscription manager affiliate included",
        "parameters": [
          {
            "name": "services",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription audit with savings analysis"
          }
        }
      }
    },
    "/api/deals/cards": {
      "get": {
        "summary": "Credit card cashback optimization for a purchase or category",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Credit card cash-back optimization \u2014 pairs with WealthPulse for card-based savings strategy",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Best card for maximizing rewards on this purchase"
          }
        }
      }
    },
    "/api/deals/stack": {
      "get": {
        "summary": "Deal stacking \u2014 combine sale + coupon + cashback for maximum savings",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Deal stacking strategy \u2014 combine store sale + coupon + cashback for maximum savings",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "retailer",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Optimal deal stack with cashback + coupon + sale"
          }
        }
      }
    },
    "/api/deals/student": {
      "get": {
        "summary": "Student discounts on software, services, food, and travel",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.05,
        "x-agent-chaining": "Student deals \u2014 UNiDAYS + Student Beans affiliates auto-appended; pairs with EduPulse",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Student discount deals with UNiDAYS and Student Beans links"
          }
        }
      }
    },
    "/api/deals/history": {
      "get": {
        "summary": "Price history and best-time-to-buy analysis for a product",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Price history analysis \u2014 CamelCamelCamel data; identifies best time to buy",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Price history with optimal buy-window prediction"
          }
        }
      }
    }
  }
}