zodiac-horoscope（黄道十二宫）

Zodiac Horoscope

Provide personalized, actionable daily guidance powered by planetary transit calculations against the user's natal chart.

Required Environment Variables

Privacy Notice

This skill collects sensitive PII (email, birth date, birth city) required for natal chart calculations. Handle with care:

• Ask for explicit user consent before collecting birth information
• Never log or expose PII in public channels or shared contexts
• Store API keys and profile IDs in environment variables, not in plain text files
• Delete cookies.txt after registration is complete

How This Helps People

• Daily decision-making: "Should I have that difficult conversation today?" → Check if confrontations are favorable or unfavorable
• Schedule optimization: Plan high-energy tasks on high-energy days, rest on low days
• Life event planning: Find the best window for job interviews, first dates, travel, or big purchases (paid tiers unlock future dates)
• Relationship insights: Romance metrics help users pick ideal date nights
• Motivation & mindfulness: Daily summaries provide a moment of reflection and intentional living

Setup

Everything can be done via API — no browser needed.

1. Register & get API key

# Send verification code (creates account if new)
curl -s -X POST https://zodiac-today.com/api/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

# Verify code (check email inbox for 6-digit code)
curl -s -X POST https://zodiac-today.com/api/auth/verify \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","code":"123456"}'

# Create API key (use session cookie from verify step)
curl -s -X POST https://zodiac-today.com/api/keys \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"My Agent"}'
# Response: {"id":"...","key":"hsk_...","name":"My Agent"}

Store the hsk_ key as environment variable ZODIAC_API_KEY. Delete cookies.txt after this step.

2. Create birth profile

curl -s -X POST https://zodiac-today.com/api/profiles \
  -H "Authorization: Bearer hsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","birthDate":"1990-05-15","birthCity":"London, UK"}'

Save the returned id as environment variable ZODIAC_PROFILE_ID.

Workflow

First-time setup for a user

1. Ask for their email, birth date, and birth city (get explicit consent — this is sensitive PII)
2. Send verification code: POST /api/auth/send-code with their email
3. Human-in-the-loop: Ask the user to check their email and provide the 6-digit code. If the agent has email access (e.g., IMAP), it may retrieve the code automatically from noreply@zodiac-today.com
4. Verify code: POST /api/auth/verify — save session cookie to a temp file (-c cookies.txt)
5. Create API key: POST /api/keys (with session cookie) — save the returned hsk_ key
6. Clean up: Delete cookies.txt immediately — it is no longer needed
7. Create profile: POST /api/profiles (with API key) — save the returned profile id
8. Store ZODIAC_API_KEY and ZODIAC_PROFILE_ID as environment variables

Daily horoscope fetch

1. Call GET /api/horoscope/daily?profileId=$ZODIAC_PROFILE_ID&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD with Authorization: Bearer $ZODIAC_API_KEY
2. Parse the response and present actionable insights

Presenting results to users

Translate raw data into practical advice:

• overallRating (1-10): Frame as "Great day!" (8+), "Solid day" (6-8), "Take it easy" (<6)
• favorable/unfavorable: Present as "Good for:" and "Better to avoid:" lists
• metrics: Highlight the standout ones — "Your energy is HIGH today, perfect for tackling that project"
• luckyColors: Suggest outfit or decor choices
• luckyNumbers: Mention casually, fun touch
• summary: Use the astrological narrative to add color, but keep advice grounded and practical

Planning ahead (paid tiers)

For users with Starter+ tiers, fetch date ranges to help:

• "What's the best day this month for my job interview?"
• "When should I plan our anniversary dinner?"
• Compare overallRating across dates and recommend the highest-rated windows

API Details

See references/api.md for full endpoint docs, parameters, tiers, and response schemas.

Example curl

curl "https://zodiac-today.com/api/horoscope/daily?profileId=PROFILE_ID&startDate=2026-02-15&endDate=2026-02-15" \
  -H "Authorization: Bearer hsk_your_api_key"