BaZi Gets Serious: Six New Analytical Endpoints for the Four Pillars

The Four Pillars of Destiny — BaZi (八字) — is not a simple system to expose correctly. The natal chart alone requires precise sexagenary cycle math: four pillars, each a pair of Heavenly Stem and Earthly Branch, derived from birth year, month, day, and hour. Get the solar term boundary wrong and an entire pillar shifts. Get the Day Master wrong and every Ten God relationship in the chart inverts.

We have been doing the natal calculation for a while. What we shipped this week is the analytical layer — the part that actually interprets the chart.

Six new endpoints, each validated against canonical doctrinal sources before a line of production code was written.

---

What We Added

Ten Gods (十神) — /chinese/bazi/{date}/ten-gods

The Ten Gods are the relational framework of BaZi. They describe how each stem in a chart relates to the Day Master — the ruling stem of the day of birth. Friend, Rob Wealth, Eating God, Hurting Officer, Indirect Wealth, Direct Wealth, Seven Killings, Direct Officer, Indirect Resource, Direct Resource. Each one has a polarity that flips depending on whether the Day Master is yin or yang.

This is the engine's most fundamental analytical layer. Every downstream interpretation touches it. We implemented the full 10×10 Day Master matrix — which means 100 unique stem-to-stem relationships computed from element relationships and polarity — and validated every one against the classic tables before deployment.

Luck Pillars (大運) — /chinese/bazi/{date}/luck-pillars

Luck Pillars are the ten-year cycles that overlay a natal BaZi chart. They are computed from the distance from the birth date to the next solar term boundary, translated into years at the traditional rate of three days per year. Each pillar is a sexagenary pair that advances through the cycle in the direction determined by birth year polarity and gender.

A complete life reading requires these. This endpoint returns the full sequence — ten pillars, each with its start age, Heavenly Stem, Earthly Branch, Five Element element, and Ten God relationship to the Day Master — computed from the natal chart.

Annual Pillar (流年) — /chinese/bazi/{date}/annual-pillar

The Annual Pillar, Liu Nian, is the year's sexagenary pair overlaid on a natal chart. It is how BaZi practitioners read the current year's influence — which Five Elements are activated, what Ten God energy is dominant, whether clashes and combinations are formed with the natal pillars.

Pass a birth date and a target year. Get back the Annual Pillar with its Ten God relationship to the natal Day Master and a computed clash-and-combination analysis against the natal chart.

Compatibility (八字合婚) — /chinese/bazi/{date}/compatibility

BaZi compatibility analysis — traditionally used for marriage timing — computed as a structural analysis of two natal charts against each other. The endpoint returns Day Master element interactions, Six Clash pairs between natal pillars, clashing and combining stems and branches, and a compatibility score derived from the doctrinal framework.

Two date inputs. Complete relational analysis. The math does not know who the people are, which is the point — it computes the structural relationship between the charts and surfaces what the tradition says about it.

Element Balance (五行) — /chinese/bazi/{date}/element-balance

Every BaZi chart has a Five Element distribution across its stems and branches, weighted by position and hidden stem inclusion. This endpoint computes that distribution — which elements are strong, average, or weak — and derives a Day Master strength assessment from it.

Day Master strength determines the entire interpretive framework of a BaZi reading. A strong Day Master benefits from elements that drain or control it. A weak Day Master needs support. Getting this wrong means every element recommendation in the reading is backwards.

We count every stem and branch in the four pillars, include hidden stems from the Earthly Branches, and weight them by position — year and month pillars carry different weights than day and hour.

Solar Terms (節氣) — /chinese/solar-terms/{year}

All 24 Solar Terms for any year, computed from our ephemeris engine to the exact minute.

The 24 Jiéqì divide the solar year into the segments that govern Chinese month boundaries and Luck Pillar computation. They are not evenly spaced calendar divisions — they are the Sun's exact ecliptic position at every 15° increment, which means they fall at different times each year and must be computed, not looked up.

Each term is returned with its Chinese name, romanization, solar longitude, and precise UTC timestamp. This is the same engine that backs our month pillar calculation — which means the Solar Terms endpoint and the BaZi natal chart agree by construction.

---

How It Was Validated

We do not ship analytical endpoints without validation against the tradition.

Before any of these endpoints were deployed, we built a canonical test suite: 56 reference cases drawn from Chinese astrology doctrinal literature covering pillar computation, Ten God polarity matrices, Hidden Stem tables, NaYin resonance, and the Six Clash pairs.

All 56 pass. Every year pillar from Geng-Zi (1900) through Jia-Chen (2024). Every Ten God relationship for both Jia and Yi Day Masters. Every Earthly Branch hidden stem — including the triple-stem branches like Yin (Wood, Fire, Earth) and Hai (Water, Wood). Every NaYin pair from the first (Sea Metal, Jia-Zi) to wrapping behavior at the cycle boundary.

The math is not approximate. It is the tradition's own arithmetic, implemented exactly.

---

Calling the Endpoints

All six endpoints are REST, authenticated with an API key, and return structured JSON. Here is a Ten Gods request:

GET /api/v2/chinese/bazi/1985-07-14/ten-gods
X-API-Key: YOUR_API_KEY

{
  "day_master": {
    "stem": "Yin",
    "element": "Wood",
    "polarity": "yin"
  },
  "pillars": {
    "year": {
      "stem": "Yi",
      "ten_god": "Friend",
      "element": "Wood"
    },
    "month": {
      "stem": "Bing",
      "ten_god": "Hurting Officer",
      "element": "Fire"
    }
  }
}

Luck Pillars work the same way — one birth date, a sequence of ten pillars with start ages computed from solar term distance. Solar Terms take a year and return all 24.

All six endpoints are available at the Pro tier and above. They cost 3 credits each — the same as comparative math endpoints. The basic natal BaZi calculation remains 1 credit.

---

Also in This Release

MCP server v3.9.2 ships alongside the new endpoints. If you are running OpenEphemeris through Claude or any MCP-compatible AI, the BaZi analytical tools are now available in the tool list.

The total public API surface is now 116 endpoints — covering Western natal and predictive, Vedic, Human Design, astrocartography, Chinese, and astronomical calendar systems in a single authenticated API.

---

BaZi is a serious analytical tradition. The practitioners who use it are precise about their craft — they work from tables, verify their pillar computations manually, cross-check the solar term boundaries. Serving that community well means the math has to be right before it is fast, documented before it is shipped, and validated against the tradition before it is trusted.

That is what we built. It is ready now.

The full documentation is in the API reference. If you are already connected via MCP, the tools are already there.