Check current API key status: tier, credit balance, rate limits, monthly cycle reset. Run this BEFORE invoking expensive endpoints (Tier 4+ at 100+ credits, Tier 6/7 at 500-5000 credits) to confirm the user has budget. Returns plain-text human-readable summary.

Estimate the credit cost of one or more endpoints WITHOUT invoking them. Returns total + per-endpoint breakdown with tier annotations. Useful when planning multi-step workflows: estimate first, ask user confirmation, then invoke. Cache TTL 5 min.

Calculate ACG lines for all planets — the geodetic map lines where each planet was on an angle at birth.

[Group: Astro-Geography] [Cost: 50 credits (Tier 3)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Calculate radius zones around ACG lines (default 700-mile orb) where planetary influence is considered active.

[Group: Astro-Geography] [Cost: 50 credits (Tier 3)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52,"point":{"lat":48.8566,"lng":2.3522},"radiusDeg":4}

LLM chat grounded in a natal chart context. Persona-tunable.

[Group: AI & MCP]

Example request body: {"message":"What does my Saturn placement mean?","chart":{"...":"..."},"language":"en"}

Coach two charts on relationship dynamics.

[Group: AI & MCP]

Example request body: {"chartA":{"...":"..."},"chartB":{"...":"..."}}

Detailed explanation of an aspect between two planets.

[Group: AI & MCP]

Example request body: {"planet1":"Saturn","planet2":"Moon","aspect":"square"}

Explain a current transit hitting your natal chart.

[Group: AI & MCP]

Example request body: {"transitPlanet":"Saturn","natalPlanet":"Sun","aspect":"conjunction"}

Find the nearest minimum brightness moment of Algol (Beta Persei) — the eclipsing variable star — within a date range.

[Group: Calendar & Cycles] [Cost: 10 credits (Tier 1)]

Example request body: {"startDate":"2024-06-01","endDate":"2024-06-30"}

Find the single nearest Algol brightness minimum before or after a given date.

[Group: Calendar & Cycles] [Cost: 10 credits (Tier 1)]

Example request body: {"date":"2024-06-15"}

Calculate the Almuten Figuris — the planet with the highest essential dignity score across the key chart positions.

[Group: Dignities & Receptions] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Calculate antiscia (mirror points along the Cancer/Capricorn axis) and contra-antiscia, plus their aspects to natal planets.

[Group: Aspects & Points] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Calculate Arabic parts (Lots) from a natal chart. Returns positions for standard lots (Fortune, Spirit, etc.) and any custom formula.

[Group: Aspects & Points] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52,"lots":["fortune","spirit","eros"]}

Calculate the Ashtakavarga benefic point table for a Vedic chart — individual bindus for each planet in each sign and the total Sarvashtakavarga.

[Group: Vedic] [Cost: 50 credits (Tier 3)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Transform aspect timelines into Gantt-style bars grouped by transit planet. Each bar shows the duration an aspect is in orb, with exact dates marked. Useful for visual transit calendars.

[Group: Aspects & Points]

Example request body: {"startDate":"2024-01-01","endDate":"2024-06-30","stepDays":1,"visiblePlanetIds":[0,1,2,3,4,5,6,7,8,9]}

Calculate a timeline of when two specific planets form an exact aspect within a date range, including enter/exact/leave dates.

[Group: Aspects & Points] [Cost: 100 credits (Tier 4)]

Example request body: {"planet1Id":0,"planet2Id":6,"aspectAngle":90,"startDate":"2024-01-01","endDate":"2024-12-31","orb":3}

Standalone aspect calculation — full inter-planetary aspect list with type / exactAngle / orb / isApplying. Uses per-pair astro.com orb matrix. Same calcAspects() as /chart but without planet positions / houses / midpoints overhead.

[Group: Calendar & Cycles] [Cost: 10 credits (Tier 1)]

Example request body: {"date":"1926-06-01","time":"09:30:00","timezoneOffset":-8,"latitude":34.0522,"longitude":-118.2437}

Day stem element + yin/yang polarity + canonical archetype description. The "self" character in BaZi from which all other pillars are interpreted.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3}

Element counts across year + month (4 of 8 chars). Identifies dominant + missing elements.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-06-15"}

All four pillars: year, month, day, hour. Day pillar uses HKO-canonical 60-jiazi cycle (anchor 1990-01-01 = Yi-Wei). Pass time to compute hour pillar; pass time + timezoneOffset for traditional 23:00-CST day-shift handling.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3}

Hour pillar via 五鼠遁 (Five-Rats-Escape) day-stem → hour-stem table. Zi-hour starts at 23:00 CST.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-06-15","time":"14:30:00","timezoneOffset":3}

10-year luck pillars sequence. Direction by gender + year-stem polarity per Ziping canon.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-06-15","gender":"male","count":8}

Month stem + branch from solar-term boundaries.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-06-15"}

Same Sheng-Ke + branch-clash analysis as yearly, but applied to a specific calendar month. Month branch resolved via mid-month jieqi.

[Group: BaZi (Four Pillars)]

Example request body: {"natalDate":"1990-05-15","targetYear":2026,"targetMonth":6}

Ten Gods classification per day master. Bi Jian/Jie Cai (peer), Shi Shen/Shang Guan (output), Pian Cai/Zheng Cai (wealth), Qi Sha/Zheng Guan (officer), Pian Yin/Zheng Yin (resource).

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-06-15"}

Year stem + branch + animal + element with yin/yang.

[Group: BaZi (Four Pillars)]

Example request body: {"date":"1990-06-15"}

10 consecutive year pillars from a given starting year.

[Group: BaZi (Four Pillars)]

Example request body: {"startYear":1990}

Compares target year pillar against natal day master + natal year branch. Returns element-flow relation (companion / mother / output / control / wealth) per Sheng-Ke cycle, branch clashes (六冲), and trine support (三合).

[Group: BaZi (Four Pillars)]

Example request body: {"natalDate":"1990-05-15","targetYear":2027}

Native customer persona that resonates with the founder's sun-sign brand voice.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Suitability of a proposed launch date for the venture type.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

High-level expansion guidance; pair with /transits for actual windows.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Founder type + strengths/weaknesses + ideal industry.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Treat the proposed founding date as a chart; returns sun/moon/ASC + theme.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Industries best suited to this founder profile.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Trine elemental partners with natural synergy.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Concise leadership archetype + key strengths.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Element-based marketing voice and campaign style.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Naming hints (syllable structure, palette, semantic field) by sign.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Element-based risk tolerance + recommended safeguards.

[Group: Business Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Founder × partner compatibility score.

[Group: Business Astrology]

Example request body: {"founder":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"partner":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}}

Analyse Cyclo-Carto-Graphy (CCG) lines: progressed ACG lines at a target date with mundane/local aspects and latitude crossings.

[Group: Astro-Geography] [Cost: 100 credits (Tier 4)]

Example request body: {"natal":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"targetDate":"2024-06-15","targetTime":"12:00:00","targetTzOffset":3}

Calculate a full natal chart: planets, house cusps, aspects, sect, and angular data for a given birth moment.

[Group: Core] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Eastern-school Bagua mapping of 9 life areas (career, knowledge, family, wealth, fame, relationships, children, helpful-people, health) onto compass sectors.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-06-15","gender":"male"}

Personal Kua number from solar-year digit sum + gender. Maps to East/West group for direction work.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-06-15","gender":"male"}

Personal 4 lucky + 4 unlucky compass directions from Kua. Standard Pa Kua mapping.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-06-15","gender":"male"}

Animal sign of birth year (Lichun / Feb 4 cutoff) plus full pillar (stem + branch + element).

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Pair compatibility score (0-100) using San He trine + Liu Chong conflict-pair canon.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"person1":{"date":"1990-06-15"},"person2":{"date":"1985-03-22"}}

Fixed-branch element + cycling-stem element + yin/yang for given solar year.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Month-branch animal — represents inner motivations and private self.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-06-15"}

Hour-of-birth branch animal — represents the deepest self. Requires birth time.

[Group: Chinese — Zodiac & Feng Shui]

Example request body: {"date":"1990-06-15","time":"14:30:00"}

Calculate a coalescent chart — the harmonic chart that resonates most strongly between two charts.

[Group: Comparisons] [Cost: 50 credits (Tier 3)]

Example request body: {"input1":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"input2":{"date":"1985-11-03","time":"08:15:00","timezoneOffset":2,"latitude":48.46,"longitude":35.04}}

Calculate a midpoint composite chart by averaging the planetary positions and house cusps of two natal charts.

[Group: Comparisons] [Cost: 50 credits (Tier 3)]

Example request body: {"chart1":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"chart2":{"date":"1985-11-03","time":"08:15:00","timezoneOffset":2,"latitude":48.46,"longitude":35.04}}

Ebertin cosmogram render data.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

All chart points in 90° cardinal modulus.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"...","withTnp":true}

22.5° / 45° / 67.5° / 90° / 135° aspects.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

Lefeldt-Brummund 22.5° subdivisions.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

A=B/C structures with sentence form.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"...","orb":1.5}

Tree per personal point.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

Ebertin's personal points midpoint hits.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

Transits hitting natal midpoints in 90° dial.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"...","targetDate":"..."}

8 Hamburg trans-Neptunian bodies.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

Witte planetary pictures A+B−C=D.

[Group: Cosmobiology / Hamburg School]

Example request body: {"...chart":"..."}

Calculate the André Barbault Cyclic Index — sum of all outer planet separations — for a date range to indicate global crisis periods.

[Group: Calendar & Cycles] [Cost: 100 credits (Tier 4)]

Example request body: {"startYear":2020,"endYear":2030}

Calculate a Davison relationship chart using the midpoint in time and space between two birth moments.

[Group: Comparisons] [Cost: 50 credits (Tier 3)]

Example request body: {"chart1":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"chart2":{"date":"1985-11-03","time":"08:15:00","timezoneOffset":2,"latitude":48.46,"longitude":35.04}}

Calculate the full 22-position Destiny Matrix per Natalia Ladini's method from birth date. Returns centre arcanum, body positions (day/month/year/centre), soul positions, karmic and resource arcana with full meaning structure for each.

[Group: Destiny Matrix] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15"}

Calculate planetary disposition chains — the recursive sequence of sign rulers leading to the final dispositor.

[Group: Dignities & Receptions] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Return disposition chains with computed x/y layout coordinates for graph visualization.

[Group: Dignities & Receptions] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

DEPRECATED in v2.0.0 — RED quality (oral Zoroastrian tradition, scattered manuscripts, no canonical reference). Slated for sunset 6 months after v2.0.0 release. Migrate to broader /reference endpoints or remove dependency. Calculate Djamaspa planetary positions for date.

[Group: Esoteric] [Cost: 10 credits (Tier 1)] [⚠️ DEPRECATED — will be removed in a future API version. Avoid using.]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Calculate the draconic chart by shifting all planet longitudes relative to the True Node (0° = True Node).

[Group: Specialized Charts] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Analyse the impact of upcoming eclipses on a natal chart — aspects to natal planets, house activations, and Saros series context.

[Group: Astro-Geography] [Cost: 100 credits (Tier 4)]

Example request body: {"natal":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"year":2024,"point":{"lat":50.45,"lng":30.52}}

Find solar and lunar eclipses within a given year or multi-year range. Returns type, date, and geographic visibility data.

[Group: Calendar & Cycles] [Cost: 100 credits (Tier 4)]

Example request body: {"year":2024,"yearsRange":2}

Return planet positions for a date range with configurable step (min 0.01 days). Max range: 1 year for sub-day steps, 5 years otherwise. Optionally filter by planetIds.

[Group: Core] [Cost: 100 credits (Tier 4)]

Example request body: {"startDate":"2024-01-01","endDate":"2024-12-31","stepDays":1,"planetIds":[0,1,2]}

Decode a numeric sequence in optional life context. Returns pattern classification, exact match, and reduced single-digit meaning.

[Group: Esoteric] [Cost: 10 credits (Tier 1)]

Example request body: {"sequence":"1234","context":"saw on receipt during career change"}

Recommend crystals scored against natal sign placements (Sun/Moon/Asc) and intent keywords. Returns top-N matches with score.

[Group: Esoteric] [Cost: 10 credits (Tier 1)]

Example request body: {"sunSign":"Aries","moonSign":"Cancer","intent":"courage","limit":5}

Scan dream narrative text for known symbols. Returns matched symbols with their meanings (recurring or single-event).

[Group: Esoteric] [Cost: 10 credits (Tier 1)]

Example request body: {"text":"I was flying over a dark forest with a wolf running below","recurring":false}

Calculate the five Ptolemaic essential dignities (rulership, exaltation, triplicity, term, face) and debilities for each planet.

[Group: Dignities & Receptions] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Full NN/SN with rulers + conjuncts.

[Group: Evolutionary Astrology]

Example request body: {"...chart":"..."}

JWG: Pluto sign+house+ruler+hard aspects.

[Group: Evolutionary Astrology]

Example request body: {"...chart":"..."}

Planets squaring nodal axis = unfinished karma.

[Group: Evolutionary Astrology]

Example request body: {"...chart":"..."}

JWG's 4-type by Pluto house quadrant.

[Group: Evolutionary Astrology]

Example request body: {"...chart":"..."}

Forrest 2008 past-life method.

[Group: Evolutionary Astrology]

Example request body: {"...chart":"..."}

Multi-generational family pattern map.

[Group: Family Astrology]

Deep parent-child synastry analysis.

[Group: Family Astrology]

Saturn return timing across a family cohort.

[Group: Family Astrology]

Inter-sibling synastry and dynamics.

[Group: Family Astrology]

System-level family astrological signatures.

[Group: Family Astrology]

Income / earning archetype by sign.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Investor type + bias + strength + pitfall by sign.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Days traditionally aligned with the sign.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Gematria-style number set per sign.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Generic caution windows (Mercury Rx, eclipses, Mars Rx, major macro aspects).

[Group: Financial Astrology]

Example request body: {"date":"2026-05-07"}

Element-based risk tolerance + suggested allocation buckets.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Element-based saving recommendations.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Sign-specific spending pattern.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Long-cycle archetype tied to Jupiter (~12y) and Saturn (~29y) returns.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Personal money (2nd) and shared resources (8th) house cusps + signs.

[Group: Financial Astrology]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}

Calculate Firdaria planetary periods — the traditional Persian time-lord system based on sect and planet order.

[Group: Prognostics] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52,"maxYears":75}

Calculate conjunctions between natal planets and fixed stars within a specified orb. Returns star details and aspect type.

[Group: Aspects & Points] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52,"orb":1}

Generate a combined forecast calendar including transits, lunar phases, ingresses, and retrograde stations for a given period.

[Group: Prognostics] [Cost: 100 credits (Tier 4)]

Example request body: {"natal":{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52},"year":2024}

Calculate Gauquelin sector positions (1–36) for all planets, indicating whether each planet is in a power zone.

[Group: Aspects & Points] [Cost: 20 credits (Tier 2)]

Example request body: {"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52}