VeilChart API — Classical Metaphysics as a Service

Quick start

Three steps from zero to your first chart.

claude mcp add --transport http veilchart https://veilchart.com/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Or point any MCP client (Cursor, Claude Desktop, your own agent) at the same endpoint. Raw HTTP works too — the endpoint speaks standard MCP JSON-RPC over Streamable HTTP:

POST https://veilchart.com/mcp
Authorization: Bearer YOUR_KEY
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"bazi_cast","arguments":{"year":1992,"month":3,"day":8,"hour":7,"minute":30,"gender":"female"}}}

Keys are issued per account at veilchart.com/my-account/mcp-access and rotate every 30 days.

Tools

Seven tools, deterministic engines for math, LLM only where prose is needed.

Tool	Input	Returns	Billing
`bazi_cast`	birth date/time, gender, optional longitude + tz	Four pillars, ten-gods, hidden stems, na-yin, voids, zodiac, ming palace, 10-year luck cycles	1 call
`bazi_five_elements`	birth date/time	Five-element strength distribution, dominant and weakest element	1 call
`tcm_search`	symptom or keyword (EN/中文)	Matching classical formulas and syndrome patterns with sources	1 call
`tcm_formula_detail`	formula name	Full composition, indication, contraindication, source book	1 call
`bazi_interpretation`	birth date/time + focus + language	LLM-written interpretation in 7 languages, classical terms explained plainly	1 call
`report_quote`	locale	Report pricing and order links	Free
`account_usage`	—	Your plan, today's usage and remaining quota	Free

Sample response

bazi_cast returns a complete, structured workbench — no scraping, no guessing:

{
  "birth": { "date": "1992-03-08", "time": "07:30", "gender": "female" },
  "pillars": [
    { "label": "Year",  "gan": "壬", "zhi": "申", "naYin": "剑锋金", "hiddenStems": ["庚","壬","戊"] },
    { "label": "Month", "gan": "癸", "zhi": "卯", "naYin": "金箔金", "hiddenStems": ["乙"] },
    { "label": "Day",   "gan": "癸", "zhi": "未", "naYin": "杨柳木", "hiddenStems": ["己","丁","乙"] },
    { "label": "Hour",  "gan": "丙", "zhi": "辰", "naYin": "沙中土", "hiddenStems": ["戊","乙","癸"] }
  ],
  "dayMaster": { "gan": "癸", "element": "水" },
  "fiveElements": { "木": 2.5, "火": 1.5, "土": 3.5, "金": 1.5, "水": 4.0 },
  "dayun": [ { "ganZhi": "壬寅", "startAge": 4 }, { "ganZhi": "癸卯", "startAge": 14 } ]
}

Fields are stable within API v1. Additions are non-breaking; removals are announced on this page first.

Billing & rate limits

Per-call wallet. Each tool call deducts from your account wallet. Free tools (report_quote, account_usage) are unmetered.
Free tier. Every account includes free daily calls — enough to evaluate every tool before paying.
Fair use. Sustained abusive traffic (key sharing, resale without agreement, hammering endpoints) leads to throttling or key revocation.
Top-ups. Wallet top-ups are self-serve from your account page. No subscription required for API access.

Reliability, versioning & data

Region & uptime

Single region (US East, NJ) behind nginx. Best-effort availability; the same engine powers veilchart.com production tools. Enterprise SLAs available on request.

Versioning

API v1 is stable. The charting engine is a validated astronomical calendar library — deterministic given the same inputs and school settings (late-Zi handling, true solar time).

Data & privacy

Birth data sent with a call is used to serve that call only. We don't sell data, don't email your users, and interpretation calls are processed per-request by our LLM provider with retention disabled where supported. Deletion on request.

Enterprise

Volume pricing, pooled wallets, custom rate limits, private deployments and invoicing — tell us what you're building.

Talk to us — hello@veilchart.com

Compliance note: outputs are cultural and educational content. They are not medical, financial or legal advice — build that framing into your product.