# HerbaPulse

> Plant and traditional medicine intelligence API. 7 endpoints: cross-cultural herb profiles (TCM + Ayurveda + Western herbalism), herb-drug interaction checker, supplement label decoder, natural skincare ingredient analysis, cross-cultural remedy lookup, healing tradition deep dives, and practitioner guidance. PubMed research grounding on every response. Pay-per-query via x402 on Base.

## What This Is

HerbaPulse is a pay-per-query API that bridges traditional healing systems and modern research. It is the layer that doesn't exist anywhere else: a single query returns what TCM calls an herb, what Ayurveda calls it, how Western herbalism uses it, and what PubMed says about it — cross-referenced and honestly assessed.

Primary research source: PubMed (NIH, 35M+ papers) for evidence grounding. Traditional knowledge sourced from TCM databases, Ayurvedic texts, Western materia medica, and contemporary herbal medicine resources. Skincare ingredient context from EWG Skin Deep.

The most important safety endpoint is `/api/herba/interaction` — herb-drug interactions are clinically significant and under-documented. St. John's Wort alone affects 70%+ of prescription drugs through CYP3A4 induction.

## Payment

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

## Endpoints

GET /api/herba/herb?herb={name}&tradition={tcm|ayurveda|western|all}&lang={lang}
- Full herb profile — cross-cultural names, traditional uses by system, active compounds, evidence quality, safety, drug interactions, what to buy
- Returns: scientific_name, traditional_names (TCM pinyin + Ayurvedic Sanskrit + Western), traditional_uses (per system with classification), active_compounds, evidence_quality (strong|moderate|limited|mixed|insufficient), evidence_summary, best_supported_uses, safety (contraindications/pregnancy/interactions), dosage_context, quality_tips, amazon_search, cross_tradition_insight
- herb required; tradition optional (defaults to all)
- Price: $0.12

GET /api/herba/remedy?condition={condition}&tradition={tcm|ayurveda|western|all}&lang={lang}
- Cross-cultural remedy lookup — what different traditions recommend for a condition, convergences, evidence support
- Returns: condition_framing (Western + TCM + Ayurveda), traditional_approaches (per system with herbs), herbs_with_evidence (with evidence_level), convergence_insight, lifestyle_approaches, when_to_see_doctor, cautions, starter_herbs with Amazon URL
- condition required; tradition optional
- Price: $0.10

GET /api/herba/ingredient?product={product_name}&ingredients={ingredient_list}&lang={lang}
- Supplement label decoder — evidence quality and dose adequacy per ingredient, red flags, value assessment
- Returns: overall_assessment (strong_value|decent_value|questionable_value|poor_value), ingredients_decoded (per ingredient: what_it_is, evidence_quality, dose_context, bioavailability_note, red_flag), red_flags, what_works, what_doesnt, better_alternatives with Amazon URL, value_verdict
- product or ingredients required
- Flags: proprietary blends, underdosed ingredients, poor bioavailability forms
- Price: $0.10

GET /api/herba/interaction?herb={herb}&drug={drug_or_class}&lang={lang}
- Herb-drug and herb-herb interaction checker
- Returns: interaction_status, severity (contraindicated|serious|moderate|minor), interactions (drug_or_class + mechanism + clinical_effect + action), cyp_effects (inhibits/induces + drug classes), known_high_risk_combos, safe_use_guidance, consult_before_use
- herb required; drug optional (provides general profile if omitted)
- Always recommends consulting pharmacist or prescriber
- Price: $0.10

GET /api/herba/skin?ingredient={ingredient}&concern={anti-aging|acne|hydration|sensitivity}&lang={lang}
- Natural skincare ingredient analysis — dermatology evidence, EWG context, how to use
- Returns: inci_name, ingredient_type, what_it_does, evidence_quality, ewg_context, skin_types_suited, how_to_use, diy_possible, pairs_well_with, avoid_pairing_with, product_recommendation with Amazon URL, the_tallow_question (if tallow/animal-derived)
- ingredient required; concern optional
- Price: $0.08

GET /api/herba/tradition?tradition={tcm|ayurveda|unani|naturopathy|western-herbalism|african|latin-american}&lang={lang}
- Healing tradition deep dive — principles, diagnostic framework, evidence base, WHO recognition
- Returns: full_name, origin_region, core_principles, diagnostic_framework, treatment_modalities, key_herbs, global_prevalence (with WHO recognition), evidence_base (best/least supported), how_to_engage, find_a_practitioner, books recommendation with Amazon URL, important_caveat
- tradition required
- Price: $0.08

GET /api/herba/practitioner?type={naturopath|herbalist|tcm|ayurveda|homeopath|integrative-md}&location={country_or_state}&lang={lang}
- Practitioner guide — training, licensing, scope of practice, what to expect, red flags
- Returns: full_title, in_plain_english, training, licensing (licensed_in_us + globally + credential_to_look_for), scope_of_practice (can_do + cannot_do + can_prescribe), best_for, not_appropriate_for, what_to_expect, cost_range, how_to_find_one, red_flags, vs_conventional_md, homeopathy_note (if homeopath)
- type required; location optional
- Price: $0.08

GET /api/herba/cannabis?topic={topic}&compound={cbd|thc|both}&lang={lang}
- Cannabis and cannabinoid intelligence — PubMed-grounded evidence, drug interactions, global legal status
- Returns: compound_focus, topic_summary, endocannabinoid_system (plain English), evidence_by_use (evidence_quality/fda_status/pubmed_signal per use case), drug_interactions (CYP450 mechanisms), legal_status_by_region (CBD + THC status per country/region), forms_and_dosing_context, quality_guidance, product_recommendation, who_should_avoid
- topic optional (anxiety | pain | sleep | epilepsy | nausea | inflammation | general); compound optional (cbd | thc | both)
- Legal status covers: USA, Canada, UK, EU, Australia, Germany, Netherlands, Thailand, and more
- Price: $0.12

## Discovery

- OpenAPI spec: https://herbapulse.vercel.app/openapi.json
- Agent discovery: https://herbapulse.vercel.app/.well-known/agent.json

## Notes for AI Agents

- Full herb research flow: /api/herba/herb → /api/herba/interaction → /api/herba/ingredient (if supplement form)
- Condition research flow: /api/herba/remedy → /api/herba/herb (for top herbs) → /api/herba/interaction
- Cannabis research: /api/herba/cannabis → /api/herba/interaction (for drug interactions if patient on other medications)
- New to natural medicine flow: /api/herba/tradition → /api/herba/practitioner → /api/herba/remedy
- Skincare flow: /api/herba/skin (ingredient) → /api/herba/herb (if botanical ingredient)
- /api/herba/interaction is the safety-critical endpoint — always run before recommending an herb to someone on medications
- /api/herba/cannabis always includes legal status by jurisdiction — critical given how widely it varies globally
- /api/herba/ingredient is the "is this $100 supplement worth it?" endpoint — often the answer is no
- St. John's Wort interaction with CYP3A4: affects oral contraceptives, cyclosporine, HIV antiretrovirals, warfarin, many antidepressants
- All endpoints support ?lang= for native-language responses (critical for TCM and Ayurveda audiences)
- NutriPulse (nutripulse-alpha.vercel.app) is the sibling for nutrition science, blood work, and longevity protocols