# Wines.bet API Reference

## Overview
Wines.bet is an autonomous market data, valuation benchmark, sommelier intelligence, and investment analytics API indexing 140,000+ fine wine vintages, 1,000,000+ historical and live market price observations, and 20,000+ certified wineries and producers. Designed for AI agents, trading systems, and developers, it operates on a pure pay-per-request model with zero API keys and zero monthly subscriptions.

## Authentication & Payment Protocol (x402 V2)
All commercial endpoints require micropayment settlement via the HTTP 402 Payment Required specification (x402 V2).
- **Network**: Base Mainnet (`eip155:8453`)
- **Settlement Asset**: USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- **Recipient Wallet**: `0x350A947254e59291FAB58430E03A86589E0D8bA8`
- **Payment Scheme**: exact

## Base URL
`https://api.wines.bet`

All endpoint paths documented below are relative to this base URL.

## Agent Workflow
1. **Discover**: Query `GET /v1/regions` or read `https://api.wines.bet/openapi.json`.
2. **Initial Call**: Make an HTTP request to any paid endpoint without credentials.
3. **402 Challenge**: The server responds with `HTTP 402 Payment Required`, returning a JSON body containing `x402Version: 2` and a Base64-encoded `PAYMENT-REQUIRED` header specifying the exact price and payment parameters.
4. **Sign & Settle**: The caller signs an authorization or transfers the exact atomic amount in USDC on Base, including the signature in the `PAYMENT-SIGNATURE` HTTP request header.
5. **Receive Response**: The server validates the proof in milliseconds and returns the requested payload with `HTTP 200 OK` and a `PAYMENT-RESPONSE` header confirming on-chain settlement.

---

## Commercial Endpoints Catalog

### 1. GET /v1/wine/price
Current real-time market price valuation oracle, fair market value, offer spread, and 30-day price trend for fine wine labels by vintage.
- **Price**: $0.005 USDC (5000 atomic units)
- **Query Parameters**:
  - `name` (string, required): Wine name, producer, or denomination (e.g. `Sassicaia`, `Tignanello`, `Barolo Monfortino`, `Ornellaia`)
  - `vintage` (integer, optional): 4-digit harvest vintage year (e.g. `2021`)
  - `country` (string, optional): 2-letter ISO country code (e.g. `IT`, `FR`)
  - `lang` (string, optional): Response language (`en` or `it`, default: `en`)
- **Example Response (200 OK)**:
```json
{
  "success": true,
  "data": {
    "wine": {
      "id": "6645a1b2c3d4e5f6a7b8c9d0",
      "name": "Sassicaia",
      "producer": "Tenuta San Guido",
      "vintage": 2021,
      "countryCode": "IT"
    },
    "pricing": {
      "currency": "EUR",
      "averagePrice": 257.4,
      "lowestPrice": 239.9,
      "highestPrice": 289.0,
      "priceSpread": 49.1,
      "priceSpreadPct": 19.08,
      "offersCount": 38,
      "trend30d": 2.96,
      "lastUpdated": "2026-09-11T00:00:00.000Z"
    }
  }
}
```

---

### 2. GET /v1/wine/history
Multi-year historical price series, annualized trend analysis, volatility index, and peak/trough benchmarks across vintages.
- **Price**: $0.010 USDC (10000 atomic units)
- **Query Parameters**:
  - `name` (string, required): Wine label or producer name
  - `vintage` (integer, optional): 4-digit vintage year
  - `country` (string, optional): 2-letter ISO country code
  - `months` (integer, optional): Historical time window in months (default: `12`, max: `60`)
  - `lang` (string, optional): `en` or `it`
- **Output**: Time-series points with average, median, and volume data.

---

### 3. GET /v1/wine/sommelier
AI Sommelier intelligence: sensory organoleptic profile (tannins, acidity, body), tasting notes, grape composition, terroir characteristics, serving suggestions, and culinary pairings.
- **Price**: $0.010 USDC (10000 atomic units)
- **Query Parameters**:
  - `name` (string, required): Wine name or denomination
  - `vintage` (integer, optional): Vintage year
  - `dish` (string, optional): Food dish or ingredient to pair (e.g. `bistecca alla fiorentina`, `truffle risotto`)
  - `lang` (string, optional): `en` or `it`
- **Output**: Detailed sensory matrix, pairing score, and sommelier tasting summary.

---

### 4. GET /v1/wine/investment
Institutional fine wine investment analytics: liquidity tier, volatility metrics, Sharpe ratio, maturity drinking window (drink from / drink until), and vintage appreciation potential.
- **Price**: $0.015 USDC (15000 atomic units)
- **Query Parameters**:
  - `name` (string, required): Fine wine name or investment-grade label
  - `vintage` (integer, optional): Vintage year
  - `lang` (string, optional): `en` or `it`
- **Output**: Investment profile, status (`market_appreciation`, `blue_chip`, `stable`), momentum, liquidity score, and financial metrics.

---

### 5. GET /v1/producers
Comprehensive certified directory of 20,000+ wineries and estates: search producers by name, region, terroir, or denomination.
- **Price**: $0.003 USDC (3000 atomic units)
- **Query Parameters**:
  - `query` (string, optional): Producer name or keyword (e.g. `Antinori`, `Gaja`, `San Guido`)
  - `region` (string, optional): Region name or slug (e.g. `Toscana`, `Piemonte`)
  - `page` (integer, optional, default: 1)
  - `limit` (integer, optional, default: 20, max: 100)
- **Output**: Producer entities with portfolio size, location, and certification data.

---

### 6. GET /v1/regions
Italian wine regions, macro-areas (Nord-Ovest, Nord-Est, Centro, Sud, Isole), prominent terroir sub-zones (e.g. Langhe, Bolgheri, Etna), official DOC and DOCG denominations, indigenous grape varieties, average price benchmarks, and top fine wine labels.
- **Price**: $0.002 USDC (2000 atomic units)
- **Query Parameters**:
  - `lang` (string, optional): `en` or `it` (default: `en`)
  - `macroArea` (string, optional): Filter by macro-area (e.g. `nord-ovest`, `nord-est`, `centro`, `sud`, `isole`)
- **Output**: 20 administrative Italian regions with terroir sub-zones, DOCG/DOC lists, key grapes, average prices, and top benchmark wines with valuation and investment tier.
- **Path Deep-Dive**: `GET /v1/regions/:slug` (e.g. `/v1/regions/sicilia`, `/v1/regions/piemonte`, `/v1/regions/toscana`) returns the complete dedicated regional dossier.

---

## Agent Integration Examples

### cURL (Direct Probe)
```bash
# 1. Probe the endpoint (returns HTTP 402 with x402 V2 payment instructions)
curl -i "https://api.wines.bet/v1/wine/price?name=Sassicaia&vintage=2021"
```

### AgentCash CLI Quickstart
```bash
# 1. Onboard your agent wallet with USDC on Base
npx agentcash onboard

# 2. Execute a live test call against Wines.bet
npx agentcash try https://api.wines.bet/v1/wine/price?name=Sassicaia

# 3. Add to your agent's persistent toolbelt
npx agentcash add https://api.wines.bet
```

### TypeScript / JavaScript (Node.js with x402 client)
```typescript
import { wrapFetchWithPayment } from '@agentcash/client'; // or any standard x402 v2 payment wrapper

const fetchWithPayment = wrapFetchWithPayment(fetch, {
  walletPrivateKey: process.env.AGENT_WALLET_KEY,
  network: 'eip155:8453',
});

const res = await fetchWithPayment('https://api.wines.bet/v1/wine/price?name=Sassicaia&vintage=2021');
const data = await res.json();
console.log('Valuation:', data.data.pricing.averagePrice, data.data.pricing.currency);
```

## Additional Resources
- Interactive Swagger UI: `https://api.wines.bet/docs`
- OpenAPI 3.1 Spec: `https://api.wines.bet/openapi.json`
- Consumer Website: `https://wines.bet`
- Support & Questions: `vinobet@gooposta.com`