{"openapi":"3.1.0","info":{"title":"Wines.bet Commercial Wine Market Data API","version":"1.0.0","description":"Official commercial API for Wines.bet (api.wines.bet). Real-time fine wine valuations, market liquidity, and investment analytics for AI agents, monetized via x402 V2 in USDC on Base.","x-guidance":"Returns real-time fine wine valuations, market liquidity metrics, order book depth, and investment recommendations. Input: wine search query, vintage, country, or ID. Output: market price trends, bid-ask spreads, liquidity tiers, Sharpe ratio, and wine catalog labels. Call when an agent needs fine wine pricing, valuation benchmarks, market liquidity, or portfolio investment analytics. Monetized via x402 V2 in USDC on Base (eip155:8453).","contact":{"name":"Wines.bet API Support","url":"https://wines.bet","email":"api@wines.bet"},"license":{"name":"Commercial API License","url":"https://wines.bet/terms"}},"servers":[{"url":"https://api.wines.bet","description":"Production Server (HTTPS)"}],"security":[{"x402":[]}],"paths":{"/health":{"get":{"summary":"Liveness Probe","description":"Returns the service operational status without checking external dependencies.","tags":["System"],"responses":{"200":{"description":"Service is alive and running","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"wine-api"},"version":{"type":"string","example":"1.0.0"}}}}}}}}},"/ready":{"get":{"summary":"Readiness Probe","description":"Verifies the application connectivity to the underlying MongoDB database.","tags":["System"],"responses":{"200":{"description":"Service and database are ready","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"wine-api"},"version":{"type":"string","example":"1.0.0"},"database":{"type":"string","example":"connected"}}}}}},"503":{"description":"Database disconnected or degraded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"degraded"},"database":{"type":"string","example":"disconnected"}}}}}}}}},"/v1/wine/find":{"get":{"summary":"Search Wine Catalog & Resolve Labels","description":"Search wine catalog by name, producer, appellation, region, and vintage. Returns matched labels with IDs, scores, and status.","tags":["Wine Discovery"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text wine, producer, or denomination query (e.g. Sassicaia, Barolo).","schema":{"type":"string","example":"Sassicaia"}},{"name":"name","in":"query","required":false,"description":"Specific wine label name (e.g. Tignanello).","schema":{"type":"string","example":"Tignanello"}},{"name":"vintage","in":"query","required":false,"description":"Four-digit harvest vintage year (e.g. 2021).","schema":{"type":"integer","example":2021}},{"name":"region","in":"query","required":false,"description":"Wine region (e.g. Tuscany, Piedmont).","schema":{"type":"string","example":"Tuscany"}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (default: IT).","schema":{"type":"string","example":"IT"}},{"name":"limit","in":"query","required":false,"description":"Maximum results to return (1-50, default: 10).","schema":{"type":"integer","default":10,"example":10}},{"name":"page","in":"query","required":false,"description":"Pagination page number (default: 1).","schema":{"type":"integer","default":1,"example":1}},{"name":"lang","in":"query","required":false,"description":"Preferred language code (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 V2 payment signature proof generated by client wallet for the payment challenge.","schema":{"type":"string"}}],"responses":{"200":{"description":"Wine catalog search results","headers":{"PAYMENT-RESPONSE":{"description":"x402 V2 settlement receipt proof","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"total":{"type":"integer","example":1},"page":{"type":"integer","example":1},"limit":{"type":"integer","example":10},"wines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"},"name":{"type":"string","example":"Sassicaia"},"producer":{"type":"string","example":"Tenuta San Guido"},"vintage":{"type":"integer","example":2021},"region":{"type":"string","example":"Tuscany"},"appellation":{"type":"string","example":"Bolgheri Sassicaia DOC"},"countryCode":{"type":"string","example":"IT"},"category":{"type":"string","example":"red"},"score":{"type":"number","example":98},"status":{"type":"string","example":"market_appreciation"}}}}}}}}}}},"400":{"description":"Missing required search parameters"},"402":{"description":"Payment required via x402 V2"},"500":{"description":"Internal server error"}}}},"/v1/wine/similar":{"get":{"summary":"Similar & Alternative Wine Recommendations","description":"Find comparable and alternative wines by region, terroir, and category for diversification and tasting recommendations.","tags":["Wine Discovery"],"parameters":[{"name":"name","in":"query","required":false,"description":"Target wine name (e.g. Sassicaia, Barolo, Tignanello).","schema":{"type":"string","example":"Sassicaia"}},{"name":"id","in":"query","required":false,"description":"Target wine MongoDB ObjectId.","schema":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"}},{"name":"vintage","in":"query","required":false,"description":"Four-digit harvest vintage year (e.g. 2021).","schema":{"type":"integer","example":2021}},{"name":"limit","in":"query","required":false,"description":"Number of similar wines to return (1-20, default: 5).","schema":{"type":"integer","default":5,"example":5}},{"name":"lang","in":"query","required":false,"description":"Preferred language code (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 V2 payment signature proof generated by client wallet for the payment challenge.","schema":{"type":"string"}}],"responses":{"200":{"description":"Similar wine recommendations","headers":{"PAYMENT-RESPONSE":{"description":"x402 V2 settlement receipt proof","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"target":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"},"name":{"type":"string","example":"Sassicaia"},"producer":{"type":"string","example":"Tenuta San Guido"},"vintage":{"type":"integer","example":2021},"region":{"type":"string","example":"Tuscany"},"score":{"type":"number","example":98},"status":{"type":"string","example":"market_appreciation"}}},"similar":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d1"},"name":{"type":"string","example":"Ornellaia"},"producer":{"type":"string","example":"Tenuta dell Ornellaia"},"vintage":{"type":"integer","example":2021},"region":{"type":"string","example":"Tuscany"},"score":{"type":"number","example":97},"status":{"type":"string","example":"market_appreciation"}}}}}}}}}}},"400":{"description":"Missing required target parameter (id or name)"},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Target wine not found"},"500":{"description":"Internal server error"}}}},"/v1/wine/price":{"get":{"summary":"Wine Market Price & Current Valuation","description":"Current wine market price, lowest/average/highest valuation, active offer count, and 30-day trend for fine wine labels.","tags":["Wine Pricing"],"parameters":[{"name":"name","in":"query","required":true,"description":"Name of the wine (e.g., Sassicaia, Tignanello, Barolo Monfortino).","schema":{"type":"string","example":"Sassicaia"}},{"name":"vintage","in":"query","required":false,"description":"Four-digit harvest year (e.g. 2021).","schema":{"type":"integer","example":2021}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (e.g., IT, FR).","schema":{"type":"string","example":"IT"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 V2 payment signature proof generated by client wallet for the payment challenge.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful wine price lookup","headers":{"PAYMENT-RESPONSE":{"description":"x402 V2 settlement receipt proof","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"wine":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"},"name":{"type":"string","example":"Sassicaia"},"producer":{"type":"string","example":"Tenuta San Guido"},"vintage":{"type":"integer","example":2021},"country":{"type":"string","example":"IT"}}},"market":{"type":"object","properties":{"currency":{"type":"string","example":"EUR"},"lowest_price":{"type":"number","example":239.9},"average_price":{"type":"number","example":257.4},"highest_price":{"type":"number","example":289},"offers_count":{"type":"integer","example":18},"as_of":{"type":"string","format":"date-time","example":"2026-09-08T02:00:00.000Z"}}}}}}}}}},"400":{"description":"Invalid request or payment signature error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_REQUEST"},"message":{"type":"string","example":"Query parameter \"name\" is required."}}}}}}}},"402":{"description":"Payment Required via x402 V2 protocol","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded payment requirements object","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","example":2},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"amount":{"type":"string","example":"5000"},"payTo":{"type":"string","example":"0x350A947254e59291FAB58430E03A86589E0D8bA8"},"maxTimeoutSeconds":{"type":"integer","example":300}}}}}}}}},"404":{"description":"Wine not found or no prices available","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"WINE_NOT_FOUND"},"message":{"type":"string","example":"No wine found matching name \"Unknown Wine\"."}}}}}}}},"409":{"description":"Ambiguous wine match (multiple possible candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"AMBIGUOUS_WINE"},"message":{"type":"string","example":"Multiple wines match the requested name."}}},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"},"name":{"type":"string","example":"Barolo Bussia"},"producer":{"type":"string","example":"Prunotto"},"vintage":{"type":"integer","example":2019}}}}}}}}}}}},"/v1/wine/market":{"get":{"summary":"Wine Market Liquidity & Order Depth","description":"Real-time wine market liquidity, bid-ask spread, active offer volume, and 30-day trading momentum benchmarks.","tags":["Wine Market Data"],"parameters":[{"name":"name","in":"query","required":true,"description":"Wine name, producer, or denomination (e.g. Sassicaia, Barolo).","schema":{"type":"string","example":"Sassicaia"}},{"name":"vintage","in":"query","required":false,"description":"Four-digit harvest vintage year (e.g. 2021).","schema":{"type":"integer","example":2021}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (default: IT).","schema":{"type":"string","example":"IT"}},{"name":"lang","in":"query","required":false,"description":"Preferred language code (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 V2 payment signature proof generated by client wallet for the payment challenge.","schema":{"type":"string"}}],"responses":{"200":{"description":"Market liquidity and trading depth metrics","headers":{"PAYMENT-RESPONSE":{"description":"x402 V2 settlement receipt proof","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"wine":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"},"name":{"type":"string","example":"Sassicaia"},"producer":{"type":"string","example":"Tenuta San Guido"},"vintage":{"type":"integer","example":2021},"country":{"type":"string","example":"IT"}}},"market":{"type":"object","properties":{"currency":{"type":"string","example":"EUR"},"lowest_price":{"type":"number","example":239.9},"average_price":{"type":"number","example":257.4},"highest_price":{"type":"number","example":289},"price_spread":{"type":"number","example":49.1},"price_spread_pct":{"type":"number","example":19.08},"offers_count":{"type":"integer","example":38},"liquidity_tier":{"type":"string","enum":["high","medium","low"],"example":"high"},"trend_30d":{"type":"number","example":2.96},"momentum":{"type":"string","enum":["positive","negative","neutral"],"example":"positive"},"as_of":{"type":"string","example":"2026-09-11T00:00:00.000Z"}}}}}}}}}},"400":{"description":"Missing required wine name"},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Wine not found or no market data"},"409":{"description":"Ambiguous wine match"},"500":{"description":"Internal server error"}}}},"/v1/wine/history":{"get":{"summary":"Wine Price History & Multi-Period Trends","description":"Historical wine price series, volatility tracking, and multi-period trend analytics (30d, 90d, 1y, all) for fine wine price index evaluation.","tags":["Wine History"],"parameters":[{"name":"name","in":"query","required":true,"description":"Name of the wine (e.g., Sassicaia, Tignanello).","schema":{"type":"string","example":"Sassicaia"}},{"name":"vintage","in":"query","required":false,"description":"Four-digit harvest year (e.g. 2021).","schema":{"type":"integer","example":2021}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (e.g., IT, FR).","schema":{"type":"string","example":"IT"}},{"name":"range","in":"query","required":false,"description":"Time horizon for historical data (\"30d\", \"90d\", \"1y\", \"all\"). Default is \"90d\".","schema":{"type":"string","enum":["30d","90d","1y","all"],"default":"90d"}},{"name":"lang","in":"query","required":false,"description":"Preferred language code (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}}],"responses":{"200":{"description":"Successful price history lookup","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"wine":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"producer":{"type":"string"},"vintage":{"type":"integer"},"countryCode":{"type":"string"}}},"history":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-08-15"},"lowest_price":{"type":"number","example":245},"average_price":{"type":"number","example":255},"highest_price":{"type":"number","example":280},"offers_count":{"type":"integer","example":14}}}},"summary":{"type":"object","properties":{"period":{"type":"string","example":"90d"},"currency":{"type":"string","example":"EUR"},"min_price":{"type":"number","example":239.9},"max_price":{"type":"number","example":289},"current_price":{"type":"number","example":257.4},"start_price":{"type":"number","example":250},"change_amount":{"type":"number","example":7.4},"change_pct":{"type":"number","example":2.96},"points_count":{"type":"integer","example":45}}}}}}}}}}}},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Wine or price history not found"}}}},"/v1/wine/investment":{"get":{"summary":"Fine Wine Investment Analysis, Returns, Risk & Liquidity","description":"Financial analytics for investment-grade fine wines. Returns multi-period returns, Sharpe ratio, volatility, liquidity grade, price spread, and drinking maturity windows for portfolio evaluation.","tags":["Wine Investment"],"parameters":[{"name":"name","in":"query","required":true,"description":"Name of the investment-grade wine (e.g. Sassicaia, Masseto, Barolo Monfortino).","schema":{"type":"string","example":"Sassicaia"}},{"name":"vintage","in":"query","required":false,"description":"Harvest vintage year (e.g. 2021).","schema":{"type":"integer","example":2021}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (default IT).","schema":{"type":"string","example":"IT"}},{"name":"lang","in":"query","required":false,"description":"Response language (\"en\" or \"it\", default \"en\").","schema":{"type":"string","enum":["en","it"],"default":"en"}}],"responses":{"200":{"description":"Comprehensive Blue Chip investment profile and financial metrics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"wine":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d0"},"name":{"type":"string","example":"Sassicaia"},"producer":{"type":"string","example":"Tenuta San Guido"},"vintage":{"type":"integer","example":2021},"category":{"type":"string","example":"red"},"appellation":{"type":"string","example":"Bolgheri Sassicaia DOC"},"countryCode":{"type":"string","example":"IT"},"status":{"type":"string","example":"market_appreciation"},"score":{"type":"number","example":98}}},"investmentProfile":{"type":"object","properties":{"status":{"type":"string","example":"market_appreciation"},"analystNote":{"type":"string","example":"Iconic Super Tuscan with stellar liquidity."},"financials":{"type":"object","properties":{"currency":{"type":"string","example":"EUR"},"currentIndex":{"type":"number","example":142.5},"averagePrice":{"type":"number","example":257.4},"priceFloor":{"type":"number","example":239.9},"returns":{"type":"object","properties":{"change24h":{"type":"number","example":0.4},"change7d":{"type":"number","example":1.2},"change1m":{"type":"number","example":2.96},"change1y":{"type":"number","example":11.4}}},"momentum":{"type":"string","example":"positive"},"liquidity":{"type":"string","example":"high"},"volatility":{"type":"string","example":"low"},"trend90d":{"type":"string","example":"bullish"},"sharpeRatio":{"type":"number","example":1.85},"priceSpreadPct":{"type":"number","example":19.08},"bidSignal":{"type":"string","example":"tight"},"retailersTracked":{"type":"integer","example":38},"asOf":{"type":"string","format":"date-time"}}},"maturity":{"type":"object","properties":{"drinkFrom":{"type":"integer","example":2028},"drinkUntil":{"type":"integer","example":2050},"currentMaturity":{"type":"string","example":"young_cellaring"}}}}}}}}}}}},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Wine not found or financial data unavailable"},"409":{"description":"Ambiguous wine match"}}}},"/v1/wine/sommelier":{"get":{"summary":"Wine Tasting Notes, Food Pairing & Sommelier Intelligence","description":"Wine sommelier intelligence with tasting notes, sensory profile, food pairing recommendations, grape varieties, tannins, acidity, body, terroir and drinking profile. Use this endpoint when an agent asks what food pairs with a wine, how a wine tastes, its tasting profile, grape characteristics, tannins, acidity, body or sommelier information. Supports Barolo, Brunello di Montalcino, Sassicaia, Tignanello, Ornellaia and other Italian wines.","tags":["sommelier","food-pairing","wine-pairing","tasting-notes","tasting-profile","tannins","acidity"],"parameters":[{"name":"name","in":"query","required":true,"description":"Wine name or denomination (e.g. Barolo, Brunello di Montalcino, Amarone).","schema":{"type":"string","example":"Barolo"}},{"name":"vintage","in":"query","required":false,"description":"Harvest vintage year (e.g. 2019).","schema":{"type":"integer","example":2019}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (default IT).","schema":{"type":"string","example":"IT"}},{"name":"lang","in":"query","required":false,"description":"Response language (\"en\" or \"it\", default \"en\").","schema":{"type":"string","enum":["en","it"],"default":"en"}}],"responses":{"200":{"description":"Comprehensive sommelier intelligence report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"wine":{"type":"object","properties":{"id":{"type":"string","example":"6645a1b2c3d4e5f6a7b8c9d1"},"name":{"type":"string","example":"Barolo"},"vintage":{"type":"integer","example":2019},"category":{"type":"string","example":"red"},"appellation":{"type":"string","example":"Barolo DOCG"},"description":{"type":"string"}}},"terroir":{"type":"object","properties":{"region":{"type":"string","example":"Piedmont"},"province":{"type":"string","example":"CN"},"denomination":{"type":"string","example":"Barolo DOCG"},"country":{"type":"string","example":"IT"}}},"producer":{"type":"object","properties":{"name":{"type":"string","example":"Vietti"},"slug":{"type":"string","example":"vietti"},"region":{"type":"string","example":"Piedmont"},"location":{"type":"string","example":"Castiglione Falletto (CN)"},"founded":{"type":"integer","example":1873},"hectares":{"type":"number","example":35},"annualBottles":{"type":"integer","example":250000},"description":{"type":"string"}}},"grapes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Nebbiolo"},"slug":{"type":"string","example":"nebbiolo"},"color":{"type":"string","example":"red"},"profile":{"type":"string"},"sensoryProfile":{"type":"object","properties":{"tannin":{"type":"number","example":5},"acidity":{"type":"number","example":4},"body":{"type":"number","example":4},"elegance":{"type":"number","example":5},"longevity":{"type":"number","example":5},"aromaticIntensity":{"type":"number","example":4}}}}}},"sommelierNotes":{"type":"object","properties":{"drinkingWindow":{"type":"object","properties":{"drinkFrom":{"type":"integer","example":2025},"drinkUntil":{"type":"integer","example":2045},"currentMaturity":{"type":"string","example":"in_drinking_window"}}},"servingAdvice":{"type":"string","example":"Optimal serving temperature: 16-18°C."},"characteristicsSummary":{"type":"string"}}}}}}}}}},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Wine not found"},"409":{"description":"Ambiguous wine match"}}}},"/v1/producers":{"get":{"summary":"Italian Wineries, Wine Producers & Wine Estates Search","description":"Search and discover Italian wineries, wine producers, wine estates and producer portfolios by winery name, region and terroir. Use this endpoint when an agent asks to find wineries, wine producers, estates or producers located in an Italian wine region. Useful for winery searches in Montalcino, Barolo, Chianti, Bolgheri, Piedmont, Tuscany and other Italian wine areas.","tags":["wineries","winery","wine-producers","wine-estates","winery-search","italian-wineries","montalcino"],"parameters":[{"name":"name","in":"query","required":false,"description":"Filter by winery name or slug.","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"Filter by region (e.g. Tuscany, Piedmont).","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Filter by country code (e.g. IT).","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number (default 1).","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Items per page (1-50, default 20).","schema":{"type":"integer","default":20}},{"name":"lang","in":"query","required":false,"description":"Preferred language (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}}],"responses":{"200":{"description":"Paginated list of producers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"total":{"type":"integer","example":180},"page":{"type":"integer","example":1},"totalPages":{"type":"integer","example":9},"producers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","example":"tenuta-san-guido"},"name":{"type":"string","example":"Tenuta San Guido"},"region":{"type":"string","example":"Tuscany"},"location":{"type":"string","example":"Bolgheri (Livorno)"},"countryCode":{"type":"string","example":"IT"},"founded":{"type":"integer","example":1940},"hectares":{"type":"number","example":75},"winesCount":{"type":"integer","example":3}}}}}}}}}}},"402":{"description":"Payment required via x402 V2"}}}},"/v1/producers/{id}":{"get":{"summary":"Get Winery Details & Portfolio","description":"Retrieve detailed information, history, and active monitored wines for a specific producer.","tags":["Commercial"],"parameters":[{"name":"id","in":"path","required":true,"description":"Producer ObjectId or slug (e.g. \"tenuta-san-guido\").","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Language (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}}],"responses":{"200":{"description":"Producer details and wines list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"producer":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"region":{"type":"string"},"websiteUrl":{"type":"string"},"wines":{"type":"array","items":{"type":"object"}}}}}}}}}}},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Producer not found"}}}},"/v1/regions":{"get":{"summary":"Italian Wine Regions, DOC, DOCG, Terroirs & Benchmark Wines","description":"Comprehensive Italian wine territory and market intelligence. Returns 20 administrative wine regions organized by macro-areas (Nord-Ovest, Nord-Est, Centro, Sud, Isole), official DOCG/DOC appellations, prominent terroir sub-zones (e.g. Langhe, Bolgheri, Etna), signature grape varieties, average price benchmarks, and top fine wine labels.","tags":["wine-regions","italian-wine-regions","DOCG","DOC","wine-appellations","wine-denominations","terroir"],"parameters":[{"name":"lang","in":"query","required":false,"description":"Language (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}},{"name":"macroArea","in":"query","required":false,"description":"Filter by Italian macro-area (e.g. \"nord-ovest\", \"nord-est\", \"centro\", \"sud\", \"isole\").","schema":{"type":"string"}}],"responses":{"200":{"description":"List of Italian wine regions with territorial and market intelligence","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"total":{"type":"integer","example":20},"macroAreas":{"type":"array","items":{"type":"string"},"example":["Nord-Ovest","Nord-Est","Centro","Sud","Isole"]},"regions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","example":"piemonte"},"name":{"type":"string","example":"Piedmont"},"macroArea":{"type":"string","example":"North-West"},"capital":{"type":"string","example":"Torino"},"color":{"type":"string","example":"#7b1e3a"},"winesCount":{"type":"integer","example":184},"producersCount":{"type":"integer","example":1250},"averagePriceEur":{"type":"number","example":88.5},"geographicAreas":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Langhe"},"terroir":{"type":"string","example":"Calcareous marls and sandstones, benchmark terroir for Nebbiolo."},"keyWines":{"type":"array","items":{"type":"string"},"example":["Barolo","Barbaresco"]}}}},"appellations":{"type":"object","properties":{"docg":{"type":"array","items":{"type":"string"},"example":["Barolo DOCG","Barbaresco DOCG"]},"doc":{"type":"array","items":{"type":"string"},"example":["Langhe DOC","Nebbiolo d'Alba DOC"]}}},"keyGrapes":{"type":"array","items":{"type":"string"},"example":["Nebbiolo","Barbera","Dolcetto","Arneis"]},"topWines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Barolo Riserva Monfortino"},"producer":{"type":"string","example":"Giacomo Conterno"},"vintage":{"type":"integer","example":2015},"appellation":{"type":"string","example":"Barolo DOCG"},"averagePriceEur":{"type":"number","example":1250},"score":{"type":"number","example":100},"investmentGrade":{"type":"string","example":"Blue Chip"}}}}}}}}}}}}}},"402":{"description":"Payment required via x402 V2"}}}},"/v1/regions/{slug}":{"get":{"summary":"Get Regional Wine Zone Deep Intelligence & Benchmark Wines","description":"Retrieve full territorial dossier, active wine counts, producer coverage, terroir sub-zones, official DOCG/DOC appellations, and top fine wine labels for a specific Italian wine region.","tags":["Commercial"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Region slug (e.g. \"piemonte\", \"toscana\", \"sicilia\", \"veneto\").","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Language (\"en\" or \"it\"). Defaults to \"en\".","schema":{"type":"string","enum":["en","it"],"default":"en"}}],"responses":{"200":{"description":"Region details and territorial intelligence","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"region":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","example":"sicilia"},"name":{"type":"string","example":"Sicily"},"macroArea":{"type":"string","example":"Islands"},"capital":{"type":"string","example":"Palermo"},"color":{"type":"string","example":"#7b1e3a"},"winesCount":{"type":"integer","example":180},"producersCount":{"type":"integer","example":850},"averagePriceEur":{"type":"number","example":44},"geographicAreas":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Etna"},"terroir":{"type":"string","example":"Black volcanic sands on the slopes of Mt. Etna."},"keyWines":{"type":"array","items":{"type":"string"}}}}},"appellations":{"type":"object","properties":{"docg":{"type":"array","items":{"type":"string"},"example":["Cerasuolo di Vittoria DOCG"]},"doc":{"type":"array","items":{"type":"string"},"example":["Etna DOC","Noto DOC","Pantelleria DOC"]}}},"keyGrapes":{"type":"array","items":{"type":"string"},"example":["Nerello Mascalese","Carricante","Nero d'Avola"]},"topWines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Etna Rosso Contrada San Lorenzo"},"producer":{"type":"string","example":"Tenuta delle Terre Nere"},"vintage":{"type":"integer","example":2021},"appellation":{"type":"string","example":"Etna Rosso DOC"},"averagePriceEur":{"type":"number","example":78},"score":{"type":"number","example":96},"investmentGrade":{"type":"string","example":"Growth"}}}}}}}}}}}}},"402":{"description":"Payment required via x402 V2"},"404":{"description":"Region not found"}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","name":"payment-signature","in":"header","description":"x402 V2 payment signature proof. Required after receiving a 402 Payment Required response with payment challenge parameters."}}}}