# ScentPulse

> Fragrance intelligence API for perfume collectors, dupe-hunters, and blind-buyers. Note-pyramid lookups, in-house batch-code freshness decoding, dupe/clone matching, blind-buy risk scoring, reformulation checks, EU allergen context, occasion/climate matching, price-per-ml value math, Middle Eastern attar/oud navigation, discontinuation watch, collection valuation, and layering guides — all via x402 micropayments on Base. Global-first: Middle East attar/oud and hot-climate performance are first-class, not footnotes.

## What This Is

ScentPulse is a pay-per-query API that synthesizes live web-grounded research and public authoritative sources (IFRA, EUR-Lex, The Good Scents Company) into structured fragrance intelligence. It does not scrape Fragrantica or Parfumo — no official API exists for either — so every claim traces back to a cited, live Tavily search result or well-established public regulatory text, never a fabricated note or rating.

## Payment

All endpoints require x402 micropayment (USDC on Base mainnet, or Solana USDC-SPL).
Protocol: x402 | Network: eip155:8453 | Asset: USDC
Payment address: 0x50ab2018c06c6E4eAA9BA52057Eb55eD284912fc

To use: send a GET request without a PAYMENT-SIGNATURE header to receive a 402 response with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header.

## Endpoints

GET /api/scent/note-profile?fragrance={name}&brand={optional}
- Returns: note pyramid (top/middle/base), accord breakdown, molecule-level odor descriptors (The Good Scents Company where CAS-identifiable), who it suits, best occasions, hot-climate performance
- Price: $0.08

GET /api/scent/batch-check?brand={name}&code={batch code}
- Returns: estimated production date/range + freshness verdict from ScentPulse's in-house deterministic decoder (Coty week-code math is exact; Estee Lauder-group and Chanel return confidence-tiered candidate years, never false precision; unsupported brands return an honest "not in our table")
- Price: $0.10

GET /api/scent/dupe-match?fragrance={name}
- Returns: ranked clone/dupe candidates (Lattafa, Armaf, Alexandria Fragrances, Dossier, ALT, etc.) with note-similarity scoring and honest quality/longevity trade-offs
- Price: $0.15

GET /api/scent/blind-buy-risk?fragrance={name}
- Returns: composite 0-100 risk score for buying unsniffed — polarizing notes, review-sentiment spread, batch variation, reformulation exposure, discontinuation risk, counterfeit prevalence
- Price: $0.12

GET /api/scent/reformulation-check?fragrance={name}
- Returns: reformulation status, documented events with triggers (IFRA amendments, ingredient bans), vintage-vs-current differences
- Price: $0.12

GET /api/scent/allergen-check?fragrance_or_ingredient={name}
- Returns: EU Regulation 2023/1545 80-allergen context, likely allergen families, and the live 31 July 2026 sell-off deadline / 31 July 2028 full-compliance deadline countdown
- Price: $0.10

GET /api/scent/occasion-match?occasion={}&season={}&climate={}&age_range={}&budget_usd={}
- Returns: recommendations with explicit hot-climate (Gulf/SEA/LatAm) projection and longevity guidance
- Price: $0.10

GET /api/scent/price-per-ml?fragrance={name}
- Returns: $/ml normalized across full bottles, sets, decants, and travel sprays, with the sweet-spot size call-out
- Price: $0.08

GET /api/scent/attar-navigator?query={name or request}
- Returns: attar/oud/CPO/bakhoor format primer, house intelligence (Ajmal, Rasasi, Swiss Arabian, Al Haramain, Arabian Oud), Western-fragrance crossover map
- Price: $0.10

GET /api/scent/discontinued-watch?fragrance={name}
- Returns: signal-based discontinuation status (stock-outs, forum chatter, resale price trend), act-now guidance, succession picks
- Price: $0.10

GET /api/scent/collection-value?bottles={URL-encoded JSON array}
- Returns: realistic resale/collector value estimate per bottle, factoring discontinued/vintage premiums and fill level — defaults to a sober reality-check, not hopeful pricing
- Price: $0.15

GET /api/scent/layering-guide?fragrances={comma-separated names}
- Returns: layering combinations that work, application order, resulting character, with Gulf attar/oud and Korean K-fragrance layering context
- Price: $0.10

## Discovery

- OpenAPI spec: https://scentpulse-xi.vercel.app/openapi.json
- Agent discovery: https://scentpulse-xi.vercel.app/.well-known/agent.json
- Free trojan page: https://scentpulse-xi.vercel.app/batch-codes.html — how to read perfume batch codes per major house

## Notes for AI Agents

- All endpoints return structured JSON with a "coverage" field reporting how many live sources were retrieved and any grounding gaps.
- ScentPulse does not scrape Fragrantica/Parfumo — grounding is via Tavily web search plus IFRA/EUR-Lex/TGSC authoritative sources.
- batch-check's decode confidence tiers (HIGH/MEDIUM/LOW/ESTIMATED/NONE) are load-bearing — treat anything below HIGH as directional, not certain.
- Disclaimer is appended automatically to every response. Nothing here is legal, medical, or appraisal advice.