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 (十神) — POST /chinese/bazi/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 (大運) — POST /chinese/bazi/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 (流年) — POST /chinese/bazi/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 (八字合婚) — POST /chinese/bazi/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 (五行) — POST /chinese/bazi/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 (節氣) — POST /chinese/bazi/solar-terms

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.

Correction (2026-10-25): two pillars were wrong when this post went out. Until version 4.1.0 (2026-08-05), every day pillar was eight places off in the sixty-day cycle, so the Day Master, the hour stem and every Ten God built on them were wrong too. Month pillars from about 8 October to 5 January were also off. The suite's day-pillar cases checked the code against a copy of its own formula, so they passed while wrong. 4.1.0 fixed both bugs, rewrote those cases to call the production code, and added a second suite checked against outside tables: Hong Kong Observatory, NAOJ, JPL Horizons, Academia Sinica and others. We re-ran the full suite against current code on 2026-10-25. It passes.

Our conventions

BaZi schools draw a few boundaries differently. A chart is only right relative to the rules it uses, so here are ours. Every response also states them in calculation_metadata.

• The year starts at Li Chun (立春), the solar term near 4 February. Send year_boundary: "cny" to start it at Chinese New Year instead.
• The day starts at 23:00, the start of the Zi hour (day_boundary: "zi_hour"). Send day_boundary: "midnight" to keep 23:00–24:00 on the same day.
• True solar time is off. Send true_solar_time: true with a latitude and longitude to turn it on.
• The clock is read as given. Daylight saving is not removed, so a birth during summer time (China used it from 1986 to 1991) gets the hour pillar of the clock on the wall.
• Solar terms are computed from JPL DE440: the Sun's apparent longitude, to the minute.

An outside reference

Jade Almanac publishes BaZi calculator conventions, a CC0 dataset showing how eight public calculators handle 13 test births at the edges: Li Chun, true solar time, and the late Zi hour. It records where conventions differ. It is not a validation of our engine.

We ran its 13 probes on our defaults on 2026-10-25. Our pillars matched Jade Almanac's calculator and the tyme4ts library on all 13 (Jade Almanac's engine is built on tyme4ts, so those two agree by construction), and matched most of the other calculators on 11. The two that differ, B1 and C2, are late-Zi births: we start the next day at 23:00, and most of the others start it at midnight.

---

Calling the Endpoints

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

POST /chinese/bazi/ten-gods
X-OpenEphemeris-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "subject": {
    "birth_datetime": { "iso": "1985-07-14T06:30:00" },
    "timezone": "Asia/Shanghai",
    "birth_location": {
      "latitude": { "decimal": 31.2304 },
      "longitude": { "decimal": 121.4737 }
    }
  }
}

{
  "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 moment, 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 on every plan, the free tier included (since September 2026). They cost 3 credits each — the same as comparative math endpoints. The basic natal BaZi calculation remains 1 credit.

Update (September 2026): the BaZi surface has grown since this post. POST /chinese/bazi/chart now renders the whole chart — pillars, Day Master, Five-Element balance and Yong Shen — as a finished SVG or PNG, on the free tier, with no client-side charting required. The current surface is always listed on the BaZi API page, which is generated from the live spec.

The endpoint paths above were also corrected in September 2026: they are POST /chinese/bazi/<name>, not the GET /chinese/bazi/{date}/<name> shape originally published here. (X-API-Key also works — the API accepts it, X-OpenEphemeris-API-Key, and Authorization: Bearer opene-… interchangeably.)

---

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.

Updated 2026-09-27: that count is from this release, back in April — the surface has grown past 120 endpoints since. See pricing for the current total.

---

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.