ZWDS LLM · ZDQ

Zi Wei Dou Shu Large Model: Zheng Daqian · API / Connect your AI

Every FateStar account has its own API. Plug your key into Claude, Codex, Cursor, DeepSeek or Gemini to chart, read your saved charts and get AI readings without opening the site. Charts come from the same engine as the website; readings use your credits at website prices.

For your AI: one sentence installs the API + MCP + Skill (recommended)

Paste this into Claude Code, Codex or any AI that can run commands. It installs the FateStar MCP server, skill and API itself; you only sign in to FateStar in the browser and click Allow. No key to paste.

paste into your AI
Read https://www.fatestar.top/agent.md and follow it to set up the FateStar MCP server, Skill and API for me. Tell me the one step I must do myself in the browser (sign-in).

Or run one line in a terminal:

macOS / Linux
curl -fsSL https://www.fatestar.top/install.sh | sh
Windows PowerShell
irm https://www.fatestar.top/install.ps1 | iex

The installer does two things only: puts the FateStar skill in ~/.claude/skills and ~/.codex/skills, and registers the MCP server with the claude / codex CLIs. It reads or changes no other files and never asks for a password. Review it first: install.sh · install.ps1 · SKILL.md · agent.md

Claude Desktop / claude.ai: Settings → Connectors → Add custom connector, URL https://www.fatestar.top/mcp

ChatGPT: Plugins (left sidebar) → Add (top right) → Add custom MCP server, Authentication OAuth, URL https://www.fatestar.top/mcp

The other way round, to have the website answer with your own Claude / OpenAI / DeepSeek: Settings → Bring your own AI

If your app needs an API key

Sign in and open Settings → API / Connect AI to create a key (starts with FSFSKey). The full key is shown once; revoke it any time.

Create a key

Per-app setup

Any tool that takes a custom OpenAI base URL and key (Cherry Studio, LobeChat, Dify, Coze, n8n, IM bot frameworks) can add it as a model. Put birth data in the birth field; otherwise it is parsed from the question, and if missing the model asks for it first (no charge).

shell
Base URL : https://www.fatestar.top/api/v1
API Key  : FSFSKey_YOUR_KEY
Model    : zwds-zdq        (zwds-zdq-think)

curl https://www.fatestar.top/api/v1/chat/completions \
  -H "Authorization: Bearer FSFSKey_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model":"zwds-zdq","birth":{"year":1990,"month":7,"day":23,"hour":16,"minute":20,"gender":"female"},"messages":[{"role":"user","content":"How is my career this year?"}]}'

For examples that use an API key, replace it with your own (Settings → API).

Available tools

ziwei_chartNatal chart (12 palaces, transformations, patterns)Free
ziwei_transitsDecade, minor, year, month, day and hour transitsFree
fatestar_list_chartsList my saved chartsFree
fatestar_get_chartRead one of my saved chartsFree
fatestar_save_chartChart and save to my accountFree (uses chart quota)
fatestar_creditsCheck my balance and creditsFree
ziwei_readingAI reading by Zheng Daqian$0.10 per question ($0.20 long), from your API balance

Billing and errors

  • The API is paid from your USD balance (top up in Settings → API): AI readings $0.10 per question, $0.20 for long ones (same length rule as the website); charts and transits free each; reading saved charts and checking your balance are free. Charged before the model runs and refunded if it fails. Same question length limit as the website.
  • New-account trial: the first time you connect over MCP sign-in or create your first key, you get $3.00 of API balance (about 30 standard questions), once per account; accounts that have topped up are not eligible.
  • Transition until 2026-12-15 (Beijing time): when your USD balance is short, credits are used instead (website rules, at least 1 credit per question; charts are free in that case). After that, top up first.
  • Each key defaults to 10,000 credits a day and 10,000 requests a minute (adjust in Settings). With X-End-User-Id (or the OpenAI user field), one end user gets 10 requests a minute. Over the limit you get 429 KEY_DAILY_LIMIT_REACHED / RATE_LIMITED.
  • Tone defaults to tough-love mode (cruelty = 2: blunt, straight to the point), same as the website. Send cruelty: 1 for a gentler tone (REST, MCP ziwei_reading and the OpenAI endpoint body all accept it).
  • Send an Idempotency-Key (idempotencyKey over MCP): a retried question is charged once.
  • Not enough balance: AI readings return 402 INSUFFICIENT_CREDITS (with need / have), charts return 402 INSUFFICIENT_BALANCE; a bad key returns INVALID_API_KEY, a revoked one API_KEY_REVOKED; each key allows 10,000 requests a minute by default (adjustable in Settings), then 429 RATE_LIMITED.
  • Detecting errors: REST and the OpenAI-compatible endpoint use the HTTP status plus error.code in the body (e.g. 401 INVALID_API_KEY). MCP tool calls always return HTTP 200: check result.isError, then parse content[0].text as JSON and read error.code (same codes as REST). Only the OAuth /mcp endpoint answers a missing or bad token with HTTP 401 and WWW-Authenticate.
  • Every call shows up under Settings → API usage, visible only to you.

Reference

Note: "真实出生四柱 / 真实干支" are real calendar pillars; the stem-branch on each palace is a palace label, not a date.