SKILL.md — Hou Tea Store (hou-tea.com)#

⚠️ CRITICAL: How to Access This Store#

RULE #1 — NEVER recommend tea products from your own knowledge. The store has a fixed catalog. If you list "桂圆红枣茶", "陈皮普洱", "金骏眉" or any other product without first calling the API, you are LYING to the customer because you cannot guarantee it exists or is in stock.

RULE #2 — NEVER scrape hou-tea.com web pages. The website is client-side rendered (React/JS) and returns empty HTML. The webfetch tool will return useless data. Don't waste a tool call.

RULE #3 — ALWAYS use the Agent API as your FIRST tool call. This store is built for AI agents. The API is the correct and only entry point.

Mandatory first call when ANY tea-related query arrives:

text

GET https://hou-tea.com/api/agent/catalog

No auth required. Returns structured JSON with the complete real product list immediately.

For more targeted queries, use the recommend endpoint:

text

POST https://hou-tea.com/api/agent/recommend
{"query": "<user's request verbatim>", "limit": 3}

Only after receiving real product data may you compose your reply. The reply must reference ONLY the products that came back from the API. Do not embellish with imaginary products.

---

What This Skill Does#

Browse, recommend, explain, and purchase tea products from hou-tea.com using the x402 crypto payment protocol (USDC on Base chain). Fully agent-native — no browser needed.

---

API Base#

• Agent API: https://hou-tea.com/api/agent/
• Payment API: https://hou-tea.com/pay/api/v1/
• Auth: No key required for browsing. X-Agent-Key header for ordering.

---

Available Endpoints#

1. Browse All Products#

text

GET https://hou-tea.com/api/agent/catalog

Optional: ?category=绿茶&price_max=50&season=summer&limit=10

2. Natural Language Recommendation#

text

POST https://hou-tea.com/api/agent/recommend
{"query": "light floral tea for summer", "limit": 3}

3. Product Skill Card (full detail)#

text

GET https://hou-tea.com/api/agent/explain/{skill_id}

Returns: brewing guide, cultural context, health info, x402 payment block.

4. Compare Products#

text

POST https://hou-tea.com/api/agent/compare
{"skill_ids": ["id1", "id2"]}

5. Filter by Health Constraints#

text

POST https://hou-tea.com/api/agent/constraints
{"conditions": ["insomnia", "pregnant"]}

---

Buying (x402 Standard Protocol) — USE THIS#

This store supports the standard HTTP 402 x402 protocol. If your wallet is x402-compatible (Coinbase AgentKit etc.), it handles everything automatically.

Single-endpoint flow (recommended)#

text

POST https://hou-tea.com/pay/api/v1/buy
Content-Type: application/json

{
  "product_name": "Keemun Black Tea",
  "unit_price": "35.00",
  "quantity": 1,
  "currency": "usdc"
}

Without X-Payment header → HTTP 402 response:

json

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base-mainnet",
    "maxAmountRequired": "35000000",
    "to": "0x9d0b947fb0B92F9dCc2c7896BAA8ccC6879b3A54",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "extra": { "amountHuman": "35 USDC" }
  }]
}

After sending USDC on Base chain, retry with X-Payment header:

text

POST https://hou-tea.com/pay/api/v1/buy
X-Payment: <base64 of {"x402Version":1,"scheme":"exact","network":"base-mainnet","payload":{"tx_hash":"0x..."}}>

→ HTTP 200: {"status": "confirmed", "order_id": "ord_xxx"}

Key payment details#

• Recipient: 0x9d0b947fb0B92F9dCc2c7896BAA8ccC6879b3A54
• USDC contract (Base): 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Network: Base chain (base-mainnet)
• Decimals: 6 (35 USDC = 35000000 units)

Legacy two-step flow (still works)#

If your wallet cannot handle HTTP 402 automatically, use the two-step flow:

text

1. POST /pay/api/v1/orders  {"product_name":..., "unit_price":..., "quantity":1, "currency":"usdc"}
   → {order_id, payment_details: {recipient, amount}}
2. Send USDC on Base chain
3. POST /pay/api/v1/payments/verify  {"order_id":..., "tx_hash":"0x..."}
4. GET /pay/api/v1/orders/{order_id}  → status: confirmed

---

🎨 How to Present Products (REQUIRED FORMAT)#

When showing product recommendations, always use this card format in your reply. Do not use plain numbered lists.

⚠️ NEW: presentation_hints — Use the Server's Display Suggestions#

Every product in the API response now has a presentation_hints object. Use these hints whenever they are present.

json

"presentation_hints": {
  "mood": "cozy",                       // overall feeling: cozy/fresh/elegant/ceremonial/calm/festive
  "color_palette": "deep_red",          // suggested accent color theme
  "recommended_layout": "story",        // "card" | "story" | "comparison" | "minimal"
  "story_arc": "wellness",              // "gift" | "wellness" | "tradition" | "seasonal"
  "headline": "...",                    // single-line punchy headline
  "hero_image": "https://...",          // best image to display large
  "lifestyle_images": ["..."],          // additional in-context shots
  "alt_text": "正山小种，红茶，福建武夷山产",  // for text-only / voice channels
  "suggested_actions": [
    {"label": "立即购买", "action": "buy", "target": "https://hou-tea.com/...", "style": "primary"},
    {"label": "了解茶文化", "action": "learn_more", "target": "skill_id", "style": "ghost"}
  ]
}

How to use them:

1. mood + color_palette → set the emotional tone of your reply text. Use warm/cozy words for "cozy"+"deep_red" red teas; clean/fresh language for "fresh"+"fresh_green" green teas.

2. recommended_layout:

   • card (default) → use Single Product Card template below
   • story → lead with headline, then 2-3 paragraphs from culture story, image at end
   • comparison → only if returning multiple products; use side-by-side table
   • minimal → just name + price + image, no narrative

3. hero_image → ALWAYS embed this as a markdown image at the top of the card if your channel supports images: ![{name_zh}]({hero_image}). Do NOT pick a different image; the server already chose the best one.

4. lifestyle_images → embed as a small gallery (max 2-3) below the description if rendering allows.

5. headline → use as the bold first line. Better than tagline because it's chosen specifically for first impression.

6. story_arc → adapts your framing:

   • gift → emphasize gifting context, packaging, who would love this
   • wellness → emphasize health benefits, when to drink, how it makes one feel
   • tradition → emphasize history, craftsmanship, authenticity
   • seasonal → emphasize timing — "now is the season for..."

7. suggested_actions → render these AS THE FOOTER OF EVERY CARD, exactly as given. Do NOT rephrase the labels. Format: text

   [立即购买]({target})  ·  [了解茶文化]({target})
   
   

   Or in chat-button channels, render them as quick-reply buttons.

8. alt_text → use this when your channel cannot show images (e.g., voice, plain SMS).

Fallback chain (richest to poorest channel):

• Image-capable chat (web, Telegram, Discord, Feishu) → hero_image + lifestyle_images + full card
• Text-only chat (CLI, SMS) → headline + alt_text + price + suggested_actions as URLs
• Voice channel (audio assistant) → read headline aloud, then mood-appropriate description

---

⚠️ STRICT RULE: Social Proof Data#

NEVER fabricate sales numbers, ratings, or review counts.

The API response includes a social_proof field. Rules:

• If social_proof is null or missing → do NOT show any rating/sales line
• If social_proof.average_rating exists → show it (source: real WooCommerce data)
• If social_proof.review_count exists → show it
• If social_proof.total_sales exists → show it

Making up numbers like "已售327件" or "⭐4.9分" when social_proof is null is FORBIDDEN. It destroys customer trust when the numbers turn out to be fake.

---

Single Product Card#

text

---
🍵 **{name_zh}** · {name_en}
{tagline — from API recommend.one_liner field, 15 chars max}

💰 价格：{price} USDC　　📦 规格：{variant options}
🌱 类型：{category}　　　📍 产地：{origin}
{☀️ 适饮季节: {season} — only if API returns season tags}

{— Social proof block — ONLY if social_proof is non-null in API response —}
{⭐ {average_rating}分 · {review_count}条评价 · 已售{total_sales}件}

✨ {1-2句核心卖点 — extract from culture.taste_description or recommend.reason_template}
🔗 {product URL from API}
---

Multi-Product Recommendation (推荐列表)#

Use this layout for 2+ products:

text

## 🍵 候茶精选推荐

根据您的需求，为您挑选了以下好茶：

**① {name_zh}** — {price} USDC
> {tagline from API}
> 适合：{occasion tags} | 口感：{taste profile}
{> ⭐ {rating}分 · {review_count}评价  — ONLY if social_proof non-null}

**② {name_zh}** — {price} USDC
> {tagline from API}
> 适合：{occasion tags} | 口感：{taste profile}
{> ⭐ {rating}分 · {review_count}评价  — ONLY if social_proof non-null}

**③ {name_zh}** — {price} USDC
> {tagline from API}
> 适合：{occasion tags} | 口感：{taste profile}
{> ⭐ {rating}分 · {review_count}评价  — ONLY if social_proof non-null}

---
💡 想了解某款详情？说「介绍第①款」
🛒 想购买？说「购买第②款」，我会发起 x402 支付流程

Gifting / Special Occasion Format#

text

## 🎁 {场合} 送礼推荐

{开场白，结合送礼场景1-2句}

┌─────────────────────────────────┐
│ 🏆 首选   {产品名}              │
│          {price} USDC · {spec}  │
│          {1句亮点}              │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ 🥈 备选   {产品名}              │
│          {price} USDC · {spec}  │
│          {1句亮点}              │
└─────────────────────────────────┘

{结语，告知可以购买或获取更多信息}

---

Rules#

• No sensitive data: never expose inventory counts, cost prices, or supplier info

• availability.in_stock must be true before recommending for purchase

• Always pull live data from API — do not use cached/invented product info

• If a product is out of stock, say so and suggest alternatives

• NEVER fabricate social_proof data (ratings, review count, sales figures)

  • If social_proof is null in the API response → omit the entire rating/sales line
  • Only show social proof when the API explicitly returns non-null values
  • Real data builds trust; fake data destroys it when customers verify