# Daymaster API — Partner Playbook

> **Who this is for:** Partners integrating the Daymaster white-label API into their own product. Give this file to your AI coding assistant (Claude Code, Cursor, Copilot) or your product team — it's self-contained and actionable.

> **Daymaster in one sentence:** The only API that returns a fused 八字 (Bazi) + 紫微斗数 (Zi Wei Dou Shu) chart plus chart-contextualised AI narrative and Tarot in a single integration.

---

## 📋 Table of contents

1. [Quick start — 60 seconds to your first call](#quick-start)
2. [API reference](#api-reference) — every endpoint, request, response, error
3. [Frontend design system](#frontend-design-system) — typography, color, component patterns
4. [Business model recommendations](#business-model) — pricing, subscriptions, seasonal plays
5. [Product ideas you can build on top](#product-ideas) — 15 concrete concepts
6. [Operational guidance](#operational) — rate limits, caching, support

---

<a id="quick-start"></a>
## 1. Quick start — 60 seconds to your first call

```bash
# Replace sk_live_… with the API key emailed to you.
curl -X POST https://daymaster.ai/api/v1/readings/generate \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-End-User-Id: your_user_42" \
  -H "Content-Type: application/json" \
  -d '{
    "birth_datetime": "1990-05-15T08:00:00+08:00",
    "longitude": 121.47,
    "latitude": 31.23,
    "gender": "male",
    "include_zwds": true,
    "language": "en"
  }'
```

You'll get back a full Bazi + ZWDS chart plus a `usage` block telling you which module was billed and your month-to-date spend. That's the whole integration surface.

---

<a id="api-reference"></a>
## 2. API reference

### Authentication

Every request: `Authorization: Bearer sk_live_…` (obtained from your account manager or minted at `/portal/keys`).

Optional: `X-End-User-Id: <opaque string>` — your own user identifier. We don't resolve it to any of our users; it just appears on your usage events for per-user billing reconciliation on your side.

### Modules + pricing

| `module_id` | Endpoint | Typical price / call | Notes |
|---|---|---|---|
| `bazi_chart` | `POST /api/v1/readings/generate` | $0.10 | Includes ZWDS. Set `include_zwds: false` to skip it — price unchanged. |
| `ai_reading` | `POST /api/v1/readings/narrate` | $0.50 | LLM narrative across 10+ life areas with tone-profile switching. |
| `ai_reading_editor` | `POST /api/v1/readings/narrate/editor` | $0.10 | Editor-only tone swap on a cached master. 20% of your `ai_reading` price. |
| `tarot` | `POST /api/v1/tarot` | $0.30 | Chart-contextualised when `reading_id` passed; generic otherwise. |
| `compatibility` | `POST /api/v1/compatibility` *(coming soon)* | $0.80 | Two-chart synastry, purpose-specific. |
| `chat` | `POST /api/v1/chat` *(coming soon)* | $0.02 per message | Always-on Q&A anchored to a stored reading. |

Prices are **frozen at event time** on `usage_events.unit_cost_usd` — retroactive changes never affect past invoices.

### `POST /api/v1/readings/generate`

Compute and persist a Bazi + ZWDS chart.

**Request**
```json
{
  "birth_datetime": "1990-05-15T08:00:00+08:00",
  "longitude": 121.47,
  "latitude": 31.23,
  "gender": "male",
  "include_zwds": true,
  "language": "en"
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `birth_datetime` | ISO-8601 with explicit offset | yes | e.g. `+08:00`. If you only have local time without timezone, resolve it client-side first. |
| `longitude` | number | yes | Positive East. Used for true-solar-time correction. |
| `latitude` | number | no | Improves accuracy at high latitudes. |
| `gender` | `"male" \| "female"` | yes | Drives luck-pillar direction. |
| `include_zwds` | boolean | no (default `true`) | Skip ZWDS compute if your product doesn't need it. |
| `language` | `"zh" \| "en"` | no (default `"en"`) | Used only for downstream narrative endpoints. |

**Response `200`**
```json
{
  "chart": {
    "bazi": { "dayMaster": "甲", "year": {...}, "luckPillars": [...] },
    "zwds": { "palaces": [...], "daxians": [...] }
  },
  "reading_id": "abc-123-def",
  "usage": {
    "event_id": 42,
    "module_id": "bazi_chart",
    "unit_cost_usd": 0.10,
    "mtd_revenue_usd": 127.50
  }
}
```

### `POST /api/v1/readings/narrate`

Takes a chart (previously generated via `POST /api/v1/readings/generate`) and returns a full AI narrative in the requested tone profile. Master analytical transcript is cached on the server; swapping `tone_profile` on subsequent calls is cheap and only re-runs the editor pass.

**Request**
```json
{
  "reading_id": "abc-123-def",
  "language": "en",
  "tone_profile": "informed"
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `reading_id` | UUID | yes | Must be a chart this tenant owns (from `POST /api/v1/readings/generate`). |
| `language` | `"zh" \| "en"` | no (default `"en"`) | Narrative language. |
| `tone_profile` | `"informed" \| "plain" \| "scholar"` | no (default `"informed"`) | Controls register. `informed` = jargon explained inline, warm voice. `plain` = zero-jargon, therapist+coach. `scholar` = classical register with citations. |

**Response `200`**
```json
{
  "reading_id": "abc-123-def",
  "reading": {
    "dayMasterLabel": "...",
    "characterArchetype": "...",
    "diseaseMedicineThesis": "...",
    "personality": "...",
    "fiveElements": "...",
    "tenGods": "...",
    "luckPillars": "...",
    "career": "...",
    "relationships": "...",
    "health": "...",
    "annualForecast": "...",
    "closingSummary": "...",
    "annualCards": "{\"careerFocus\":\"...\",\"overallFortune\":\"...\",\"opportunityArea\":\"...\",\"watchOut\":\"...\"}"
  },
  "master_reading": { /* raw analytical output (all jargon, max depth) */ },
  "tone_profile": "informed",
  "tone_profile_applied": true,
  "tone_profile_error": null,
  "language": "en",
  "master_prompt_version": 4,
  "editor_prompt_version": 1,
  "usage": {
    "event_id": 42,
    "module_id": "ai_reading",
    "unit_cost_usd": 0.50,
    "mtd_revenue_usd": 623.50
  }
}
```

**Latency**: ~30-60s first call (4-chunk generation + editor pass). Tone-profile swaps on a cached master are ~5-10s (editor only).

**Cost optimization**: if you call `narrate` once per reading, you pay once for the master + once for the editor. If you later want a different tone profile for the same reading (e.g. user clicks a "plain" toggle), pass the same `reading_id` — the server uses the cached `master_reading_data` and only re-runs the editor.

**Editor-failure semantics (partial success)**: the reading is produced in two stages — master generation (chunks 1-4) then an editor rewrite into the chosen tone. If the editor pass fails while chunks succeeded, we:

1. Set `tone_profile_applied: false` and put the failure reason in `tone_profile_error` (e.g. `editor_502:upstream_timeout`).
2. Populate `reading` with the raw master transcript so your UI always has readable content — not a blank object.
3. **Half-refund** the unit cost via a `rollback` ledger entry with `{ partial: true, rollback_of: "ai_reading_tone" }`. Chunks succeeded, so you keep the generation half; we return the tone half.

When you see `tone_profile_applied: false`, retry the editor on its own against the same `reading_id` (same endpoint, same tone_profile) once upstream recovers — it'll use the cached master and you'll only pay the editor half again.

### `POST /api/v1/readings/narrate/editor`

Editor-only tone swap on a reading that already has `master_reading_data`. Same output shape as `narrate`, different billing: this endpoint refuses to run the 4-chunk master generation and only invokes the editor pass, billed against the `ai_reading_editor` module (~$0.10 by default — **20% of your `ai_reading` price**, auto-configured when you're onboarded).

Use this when the end-user explicitly toggles a tone profile ("plain" ↔ "scholar") after seeing an initial reading. `narrate` with the same `reading_id` also works on a cached master, but bills at the full `ai_reading` price even though only the editor runs — this endpoint makes the cheaper intent explicit.

**Request**
```json
{
  "reading_id": "abc-123-def",
  "language": "en",
  "tone_profile": "plain"
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `reading_id` | UUID | yes | Must be a chart this tenant owns **and** must already have `master_reading_data` populated (i.e. you've called `narrate` on it at least once). |
| `language` | `"zh" \| "en"` | no (default `"en"`) | |
| `tone_profile` | `"informed" \| "plain" \| "scholar"` | no (default `"informed"`) | |

**Response `200`** — same shape as `narrate`, minus `chart_data` fields. `tone_profile_applied` is `true` and `tone_profile_error` is `null` on success; `usage.module_id` is `"ai_reading_editor"`.

**Errors specific to this endpoint**

| Status | `error` code | Meaning |
|---|---|---|
| `403` | `module_disabled` | The `ai_reading_editor` module is not enabled on your tenant. If you have `ai_reading`, ask us to run `supabase/migrations/add-ai-reading-editor-module.sql` for you (it's a one-line insert, no downtime). |
| `404` | `not_found` | `reading_id` doesn't exist for your tenant. |
| `409` | `master_missing` | No `master_reading_data` on this reading. Call `POST /api/v1/readings/narrate` first to generate the master, then use this endpoint for subsequent tone swaps. |
| `502` | `editor_failed` | The editor itself crashed (all three models in the fallback chain returned errors). **Full refund** — unlike `narrate`'s editor-after-chunks case, nothing else ran here so the entire unit cost is rolled back. Retry with exponential backoff. |

### `POST /api/v1/tarot`

Seeded shuffle + draw, optionally contextualised by a previously-generated chart.

**Request**
```json
{
  "spread_id": "past_present_future",
  "question": "Should I take the new job offer?",
  "reading_id": "abc-123-def",
  "lang": "en",
  "skip_llm": false
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `spread_id` | `"daily" \| "past_present_future" \| "situation_action_outcome" \| "celtic_cross" \| "year_ahead"` | yes | |
| `question` | string (≤500 chars) | yes | Rendered verbatim in the LLM prompt. |
| `reading_id` | UUID | no | If set, cards are interpreted through the user's Day Master + current Da Yun + 流年. Must be a chart you own. |
| `seed` | integer | no | Pass for reproducible draws (same seed = identical cards). Auto-minted otherwise. |
| `lang` | `"zh" \| "en"` | no (default `"en"`) | |
| `skip_llm` | boolean | no (default `false`) | Return deterministic draw only, no narrative. Same billed price. |

**Response `200`** includes `tarot_reading_id`, `cards[]`, `llm_response` (prose), `ai_model` (which provider served), and the same `usage` block.

### Error codes

| Status | Meaning |
|---|---|
| `400` | Invalid/missing request field. `error.message` explains which one. |
| `401` | Missing or invalid API key. |
| `402` | Tenant wallet exhausted. Top up before retrying. |
| `403` | Key revoked · tenant paused · module not enabled for your tenant. |
| `404` | `reading_id` not found (or not owned by your tenant). |
| `409` | Precondition wrong (e.g. `narrate` called on a `reading_id` with no chart yet — call `/generate` first). |
| `422` | Chart could not be computed (invalid birth inputs — e.g. impossible date). |
| `502` | Chart generation failed (LLM chunks crashed after the fallback chain: Haiku → DeepSeek → GPT → Kimi). Full refund issued. For editor-only failures see the partial-success semantics above — the call returns `200` with `tone_profile_applied: false`. |
| `503` | Database or internal secret temporarily unavailable. Retry with exponential backoff. |

Every error response is JSON: `{ "error": "<code>", "message": "<human-readable>" }`.

### Privacy: no-name narrative guarantee

AI readings are written **strictly in second person** ("you"). We never embed the end-user's name, alias, or nickname in the narrative body — even if your request sends one. This is enforced at the system-prompt layer, pinned with source-level tripwires, and bumped via `master_prompt_version` whenever the guarantee changes.

**Why this matters to you:** we cache readings by chart signature (pillars + gender + language + year) and can serve one partner's reading to another partner's end-user with the same chart. Because no names appear in the text, this reuse is always safe — no PII leaks across tenants. If you rely on per-user personalisation beyond chart data (e.g. inserting the user's preferred name in your UI), do it on your side after we return.

Current guarantee: `NARRATIVE_PROMPT_VERSION = 4`. Any future bump that changes this rule will be announced 30 days ahead in the changelog.

### Versioning

`/api/v1/*` is stable. We never change the response shape of an existing endpoint without a version bump. New endpoints within v1 are additive — your existing integration never breaks when we ship new modules.

Two prompt-version stamps you can pin against:

- `master_prompt_version` — the analytical transcript (chunks 1-4). Currently `4`.
- `editor_prompt_version` — the tone rewrite layer. Currently `1`.

Both appear on every `/narrate` response so you can detect when we've updated the underlying model + rerun if desired.

### Rate limits

Default **60 req/min per tenant** (all modules combined). Raise on request; we store `rate_limit_per_min` per module on your tenant so we can adjust without code changes on your side. Hitting the limit returns `429` with `Retry-After` header.

### Month-to-date usage

Every successful response includes `usage.mtd_revenue_usd` so you can budget client-side without a second round trip. For detailed usage, log into the partner portal at `https://daymaster.ai/portal` with your API key (read-only mode) or with your invited email account.

---

<a id="frontend-design-system"></a>
## 3. Frontend design system

Recommendations, not requirements. Your product can look however you want — our API returns clean JSON and never constrains your UI. The guidance below captures patterns that have worked for us on the B2C app and that carry over well to destiny / tarot / wellness verticals.

### 3.1 Typography

Metaphysics content reads best with a serif anchor. We recommend two families:

| Role | Font | Weight | Scale |
|---|---|---|---|
| Display (hero, card names) | **Noto Serif SC** (or Cormorant Garamond, Playfair Display) | 300–400 | 28 / 36 / 48 / 64 |
| Body (paragraphs, card meanings) | Same serif at 300 | 300 | 13 / 14 / 15 |
| UI / buttons / labels | **Inter** or system sans | 400–500 | 10 / 11 / 12 |
| Accent (rank numbers, glyphs) | **Georgia** or serif number style | 400 | 14 / 18 / 28 |

Mixing one serif + one sans is the entire type system. Resist the urge to add a third family.

### 3.2 Color palette

Core neutrals + a single accent is enough for the whole product.

```css
/* Daymaster brand palette — CSS custom properties */
:root {
  /* Neutrals */
  --bg:            #FCFBF7;   /* warm cream, never pure white */
  --surface:       #FFFFFF;
  --ink:           #0A0A0A;   /* body text */
  --ink-soft:      #3A3A3A;
  --muted:         #888888;
  --hairline:      rgba(0,0,0,0.08);

  /* Brand accent — antique gold */
  --gold:          #B8860B;
  --gold-tint:     #F5D98A;
  --gold-bg:       rgba(184,134,11,0.08);

  /* Wu Xing element colors — use sparingly for card accents */
  --wood:          #2D8B4E;   /* 木 emerald */
  --fire:          #C4382A;   /* 火 crimson */
  --earth:         #B8860B;   /* 土 ochre (= gold) */
  --metal:         #8C8C8C;   /* 金 silver */
  --water:         #2563EB;   /* 水 indigo */

  /* Semantic — don't use red for errors in a destiny product; */
  /* prefer dignified muted tones that don't trigger alarm fatigue. */
  --error:         #A03020;
  --error-bg:      #FFF4F0;
  --success:       #2E7D32;
}
```

### 3.3 Spacing + rhythm

Use a 4px baseline grid. Card interiors breathe at 16/20/24; sections at 40/56/80.

### 3.4 Component patterns

Four primitives cover most tarot / bazi / ZWDS UI.

**A. Stat cards** — for MTD usage, balance, scores.
```
┌──────────────────────────────┐
│ LABEL (uppercase, 10px, gold)│
│                              │
│ 1,247         (28-36px, 300) │
│                              │
│ subtitle (11-12px, muted)    │
└──────────────────────────────┘
```

**B. Card-in-grid** — for tarot cards, chart summaries, compatibility pairs. 2:3 aspect ratio with element-tinted hairline border + corner flourishes.

**C. Ornate dividers** — horizontal gold line with a centered `✦` glyph. Use between major sections, not within them.

**D. Accordion / collapsible section** — every life area in a Bazi reading (career / wealth / relationships / health / etc.) should be collapsible. Readings are long; forcing the whole thing on screen tires the reader.

### 3.5 Mobile

- **Grid rule**: use `minmax(min(100%, Xpx), 1fr)` pattern (not `minmax(Xpx, 1fr)`) so columns auto-stack on narrow viewports without a JS breakpoint hook.
- **Touch targets**: 40×40 minimum for icon buttons. Key UI (sign-out, sidebar toggle) on mobile should be larger than on desktop, not smaller.
- **Tables**: never render raw `<table>` on mobile. Transform rows into stacked cards with inline key/value pairs.

### 3.6 Avoid

- **Red for fortune-positive outcomes** outside Chinese markets — reads as warning / alarm.
- **Photorealistic "mystic" imagery** (crystal balls, glowing hands). Dated, cheap-feeling, alienating to modern buyers.
- **Purple gradient neon**. Defaults of 2018-era astrology apps; repels men and serious buyers.
- **Emojis in body copy**. Fine in labels / CTAs, noise in paragraphs.
- **Three or more font families**. Strictly two.

---

<a id="business-model"></a>
## 4. Business model recommendations

Your COGS for a deeply-personalised reading is typically $0.10–$0.50 depending on modules used. Your customer's willingness-to-pay for that same experience is **$15–$100** in most markets. The gap is the business — how you structure capture of it determines whether your unit economics are 10% margin or 90%.

### 4.1 The four pricing archetypes

Pick one. Don't try to run multiple in parallel in the first year — it fragments your customer mental model and kills LTV comparisons.

#### Archetype A — Per-report pricing ($29–$149 per reading)

**How it works:** Customer arrives, fills in birth details, pays $29 for a personality report or $99 for a life-path premium bundle. One-and-done transaction.

**Unit economics:** At $29 retail · $0.50 COGS · 3% Stripe fees + 15% ad costs + 5% support ≈ **75% gross margin**. Very capital-efficient.

**Best for:** Partners with strong acquisition (existing audience, email list, creator reach). Content-marketing friendly because every report generates a shareable artefact.

**Weakness:** No recurring revenue. LTV = 1–2 transactions/customer. You fight the acquisition treadmill forever.

#### Archetype B — Subscription ($9.99–$24.99 / month)

**How it works:** Unlimited readings + daily guidance + tarot draws for a monthly fee. Substitutes for the "I want to check my chart about this thing" impulse purchase.

**Unit economics:** At $14.99/mo · avg 6 readings + 10 tarot draws · COGS ≈ $3.50/mo ≈ **76% margin**. Critically, blended LTV is 8–14 months → $120–$210 per customer, 4–8× higher than per-report.

**Best for:** Partners with light ongoing engagement (social proof, email nurture, push notifications). CHANI, Sanctuary, Bazi.ai all operate here.

**Weakness:** Churn is the whole game. Daily value prop must be real, not pretend.

#### Archetype C — Consultancy / professional services ($200–$2,000+)

**How it works:** You use the API to instrument chart analysis for a human consultant who then conducts a 60–90 minute reading over Zoom. The API is your research assistant; the consultant is the product.

**Unit economics:** At $500/session · $2 API cost · 50% to the consultant ≈ $248 net margin. Low-volume, high-margin.

**Best for:** Partners with access to a trained consultant network (Bazi practitioners, astrologers, life coaches). Lillian Too's and Joey Yap's trainee networks are the model.

**Weakness:** Doesn't scale linearly; each consultant is a bottleneck. But it's the most defensible position in the category because humans + tech > either alone.

#### Archetype D — Embedded feature in a non-metaphysics product

**How it works:** A dating app adds "compatibility reading" as an unlock feature. A couples-therapy app adds a "love language + destiny profile" onboarding. A parenting app offers a "Chinese naming suggestion" add-on. Destiny isn't your core product; it's a feature that improves retention of your core product.

**Unit economics:** API cost is absorbed as CAC / retention cost. The ROI is measured in the core product's KPIs (DAU, LTV), not in direct reading revenue.

**Best for:** Partners with an existing product who want to differentiate without building a new team.

**Weakness:** Discovery is internal to your existing user base; you don't benefit from metaphysics-native search traffic.

### 4.2 Free tier architecture

Whatever archetype you pick, some kind of free tier is non-negotiable for B2C acquisition.

**What to give away:**
- ✅ Basic Bazi chart (four pillars, Day Master, no narrative). Cost to you: $0.10.
- ✅ One short teaser paragraph from the reading ("your core drive is…"). Cost: small LLM call, maybe $0.02.
- ✅ Element distribution bar chart. Free — comes with the chart.
- ✅ One zodiac compatibility blurb (free, purely deterministic).

**What NOT to give away:**
- ❌ Full AI narrative across 10+ life areas — that's the $29 product.
- ❌ Luck-pillar timeline with ages annotated — the "when does my good decade start" moment is your strongest paywall.
- ❌ Tarot draws — every draw costs you a real LLM call; free tarot is a cash bonfire.

**War-fog technique:** show the full reading's *structure* (section headers, peak age, timeline axis) but blur or lock the actual content until unlocked. Communicates "this is comprehensive" without giving it away.

### 4.3 Seasonal revenue patterns

These are real. Plan your launch, promotion, and inventory around them.

| Window | Peak month | What buyers want | Price sensitivity |
|---|---|---|---|
| **Chinese New Year** | Jan–Feb | Year ahead forecast, yearly flying-stars report | Low (cultural obligation) |
| **Valentine's / Q1** | Feb | Compatibility + relationship reading | Mid |
| **Wedding season** | May–Aug (Western) / Oct–Dec (Chinese) | Compatibility + auspicious date | Low |
| **Back-to-school** | Aug–Sep | Kids' chart, naming, career guidance | Mid |
| **Q4 holidays** | Nov–Dec | Gift readings, friend/family bundles | Mid-high (gift category) |
| **New Year resolutions** | Dec 26 – Jan 15 | Life path, career pivot, health-year ahead | Mid |

CNY alone can be 40% of annual Q1 revenue in this category — not a joke. Ship your CNY product in **October** so content ranks by January.

### 4.4 Pricing tiers that actually work

If you're going to stack tiers, here's a structure that reliably produces a "middle converts at 70%" goldilocks effect:

| Tier | Price | Includes | Ratio |
|---|---|---|---|
| **Essential** | $29 | Chart + one life-area narrative | 1× |
| **Complete** *(hero)* | $79 | Full 10-area narrative + year ahead + 3-card tarot | 2.7× |
| **Master** | $199 | Complete + 30-min human consultation + follow-up tarot pack | 6.9× |

The middle tier is the anchor. The bottom exists to make the middle feel generous. The top exists to make the middle feel like a bargain. Most buyers pick Complete.

### 4.5 Affiliate / partner splits

If you distribute through creators (astrology YouTubers, wellness influencers, coaches):

- **Base commission**: 25–35% on first purchase. Below 20% = creators won't bother. Above 40% = kills your margin and attracts spammy affiliates.
- **Lifetime share** (optional): 10% of subscription for 12 months. Makes creators treat you like a long-term partner.
- **Payout cadence**: monthly via Stripe Connect or PayPal. Net-30 kills creator trust.

### 4.6 Cost controls for high-volume operators

If you hit 10k+ readings/month:

- **Cache chart data per birth tuple** on your side. The same `(datetime, longitude, gender)` produces the same chart — recompute in your own DB instead of hitting our API twice.
- **Batch-generate overnight** for predictable-demand use cases (daily guidance emails). Our Anthropic-backed endpoints use Batch API under the hood when latency allows.
- **Negotiate volume pricing**. Above 50k calls/month we will meet you on price — email `api@daymaster.ai` with projected volume.

---

<a id="product-ideas"></a>
## 5. Product ideas you can build on top

Concrete concepts. Each one uses the API in a specific way we've seen work — or that we'd build ourselves if we had the audience.

### Consumer apps

**1. Daymaster — daily personalized guidance (iOS/Android)**
Ship a push notification every morning with a one-paragraph reading keyed to the user's Day Master × today's pillar. Free for first 7 days, then $4.99/mo. Modules used: `bazi_chart` (once at signup) + `chat` (once per day). Retention analog: Co-Star / Calm.

**2. Mingpan — minimalist chart wallet**
A "library" of charts for the user's friends/family. Every person they care about gets a saved Bazi + ZWDS. Core loop: "what does my sister's chart say about her current job anxiety?" Free tier: 3 saved charts; Premium ($7.99/mo): unlimited + monthly forecasts for each. Modules: `bazi_chart` + `ai_reading`.

**3. Bond — couples compatibility subscription**
Two partners each upload their birth data. App returns a synastry report, identifies six flash-point zones (communication, fighting style, intimacy, money, parenting, in-laws), and pushes monthly check-ins keyed to the composite chart. $19.99/mo. Modules: `bazi_chart` (×2) + `compatibility` + `chat`.

**4. Tarot Journal — daily card practice**
Morning draw. Evening reflection prompt. Weekly streak. Monthly year-ahead spread. $9.99/mo. Modules: `tarot` (1 per day = 30/mo = $9 COGS, 10% margin alone → needs upsell to feng-shui or compatibility to hit 60%+ blended).

**5. Auspicious Date — wedding / move / launch planner**
Submit two charts (or one for solo). App returns a ranked list of dates in the next 180 days with reasoning. $29 one-time per query. Modules: `bazi_chart` + custom compute on top (the "auspicious date" endpoint ships Q2 2026).

### B2B / embedded features

**6. Corporate wellness add-on (HR benefits platform)**
Existing HR SaaS (Headspace, Lyra, Modern Health) adds a "Personality & Life Path" module for employees. Company pays $2–$5/employee/month. Employees access via SSO. Retention-as-a-service — makes the HR tool stickier. Modules: `bazi_chart` + `ai_reading`.

**7. Dating app compatibility unlock**
Existing dating app (Hinge, Bumble, the next Hinge) adds an in-app purchase: $2.99 to see your destiny-fit score with a match. Incremental revenue per swipe cluster. Modules: `compatibility` called with `X-End-User-Id` as the Hinge profile ID. No new infra needed on dating app side — our API handles persistence.

**8. Parenting / baby-naming service**
Chinese parents want names that balance the baby's Bazi. An API-backed generator produces candidate names, each scored against the child's Day Master. White-label to Chinese-diaspora parenting sites. Modules: `bazi_chart` + our soon-to-ship `name_suggestion` module.

**9. Financial advisor differentiation**
Wealth manager or financial planner offers a free "Financial Personality Report" to prospects. Uses career + wealth palaces as conversation starter. Converts 30% better than generic Myers-Briggs because it's novel + personalized. Modules: `bazi_chart` + `ai_reading`.

### Agency / creator services

**10. Astrology creator's starter SaaS**
A YouTuber or TikTok astrologer launches a $9.99/mo subscription app for their audience. Every month, subscribers get: personalized monthly forecast + one tarot draw + access to the creator's Q&A live. Creator keeps 70%, we charge for the $0.50–$2 API cost per subscriber. Modules: full stack.

**11. Corporate team-building workshop kit**
Package: chart-based team report for 10 employees + 90-minute facilitated Zoom session. $2,000 per team. Sold into HR / OD buyers. Modules: `bazi_chart` + `ai_reading` + `compatibility` (for team dynamics). Human consultant layer captures most of the margin.

**12. Content farm — SEO landing pages**
Build 60 per-day-pillar landing pages (甲子 / 乙丑 / … / 癸亥), each a deep personality profile. SEO-optimized for "Jia Zi personality" / "甲子日 特点" etc. Monetize with affiliate links back to your reading product. Modules: `bazi_chart` once per landing page (60 total calls = $6 content cost).

**13. Gift bundle — "destiny reading gift card"**
Retail product: $49 gift card that unlocks a full reading for the recipient. Sold in gift shops, corporate gifting platforms, weddings. Physical package with QR code. Margins on gift category are 60%+ because price elasticity is near zero. Modules: `bazi_chart` + `ai_reading` per redeemed card.

### Niche verticals

**14. Pet birth chart (yes, really)**
For the pet-loving demographic. Same Bazi algorithm works for pets (birth datetime). "Your cat is a fire-dominant drama queen; here's why she yells at 3am." $12.99 per pet. Pure LTV play — cat people will pay for their cat. Modules: `bazi_chart` + `ai_reading` with a pet-tuned system prompt.

**15. Meditation app guided sessions**
Existing meditation app (Calm, Waking Up, Ten Percent Happier) adds "Personalized sessions keyed to your chart." User's dominant element selects the session type (fire-dominant → calming breathwork; metal-dominant → structured clarity meditation). Modules: `bazi_chart` once; content is your existing audio library re-tagged.

### What we won't help you build

**Anti-ICP — don't build these with our API:**
- **Predictive stock-picking / lottery-number generation**. Not our vertical. Regulatory risk for everyone.
- **Medical or mental-health diagnosis**. Chart is a reflection tool, not a diagnostic one.
- **Revenue-at-any-cost dark-pattern apps**. Endless-subscription traps damage the entire category.
- **Anything that passes our output off as your own proprietary model**. Our terms require "Powered by Daymaster" or equivalent attribution in at least one user-visible place.

---

<a id="operational"></a>
## 6. Operational guidance

### Support

- **Technical questions** (API errors, rate limits, new endpoints): `api@daymaster.ai` — 24h turnaround.
- **Billing / invoice questions**: `billing@daymaster.ai` — monthly invoice issued on the 1st.
- **Product / partnership** (co-marketing, volume pricing, feature requests): your assigned account manager.

### SLA

- **/api/v1/readings/generate**: 99.9% uptime target. p95 latency < 500ms (chart compute is deterministic; no LLM).
- **/api/v1/tarot**: 99.5% uptime target. p95 latency < 6s (includes LLM call). Fallback chain: Claude Haiku → DeepSeek → GPT-4o → Kimi. `fellBack: true` in the response tells you which provider actually served.
- **Planned maintenance**: announced at least 48h in advance via email to your contact address. Scheduled outside 6am-2am UTC windows.

### Monitoring on your side

Minimum set of alarms we recommend you wire up:

1. **5xx spike** on our API from your edge (threshold: >1% over 5 minutes)
2. **Cost anomaly** — MTD revenue projects to 2× typical monthly — may indicate an uncapped abuse vector on your side
3. **Rate limit hits** (429 responses) — signals you need to request a limit bump

### Attribution requirement

Your product must display "Powered by Daymaster" or "Chart intelligence by Daymaster" in at least one user-visible place (footer, about, credits, or settings — your choice). If you need a logo pack, reply `LOGO` to any email thread with your account manager.

---

## Appendix — Glossary

| Term | Meaning |
|---|---|
| **Bazi** / 八字 | "Eight Characters" — Chinese birth chart based on Year/Month/Day/Hour pillars. |
| **Day Master** / 日主 | The stem of the day pillar; the chart's central reference point. |
| **Da Yun** / 大运 | Major Luck Pillar — a 10-year life period with its own stem/branch pair. |
| **Liu Nian** / 流年 | Annual pillar — each calendar year has a stem/branch interacting with the chart. |
| **ZWDS** / 紫微斗数 | Zi Wei Dou Shu — "Purple Star Astrology". 12-palace chart with 14 main stars. |
| **Palace** / 宫 | One of 12 life-area zones in the ZWDS chart (Life, Wealth, Career, Spouse, etc.). |
| **Wu Xing** / 五行 | Five Elements (Wood, Fire, Earth, Metal, Water). Drives compatibility + element bridge. |
| **Yong Shen / Ji Shen** | Favorable / unfavorable elements for a given chart. |
| **Tarot spread** | A named arrangement of card positions (e.g. Past/Present/Future = 3 positions). |

---

## Changelog

- **v1.2** (2026-04-24) — Shipped `POST /api/v1/readings/narrate/editor`. Dedicated endpoint for explicit tone swaps on a cached master, billed against the new `ai_reading_editor` module (~$0.10, 20% of `ai_reading`). Returns `409 master_missing` if called before `narrate`; `502` triggers a **full** refund (not half, because no chunks ran). The `ai_reading_editor` module is auto-enabled at onboarding for any tenant that has `ai_reading` enabled.
- **v1.1** (2026-04-21) — Shipped `POST /api/v1/readings/narrate` with three tone profiles (informed / plain / scholar), cached-master tone swaps, and partial-success semantics: on editor failure we return `tone_profile_applied: false`, populate `reading` with the master transcript, and half-refund the call. Documented the no-name narrative guarantee and bumped `master_prompt_version` to `4`. Added `402` (wallet exhausted) and `409` (precondition-wrong) to the error table.
- **v1.0** (2026-04-20) — Initial playbook with API ref, design system, business model, product ideas.

*Questions not covered here? `api@daymaster.ai`.*