---
name: mingge
description: Chinese metaphysics by a deterministic engine: BaZi charts with archetype, scores, luck-decade curve and life-event timing; Zi Wei Dou Shu charts and limits; Qi Zheng Si Yu (Chinese sidereal astrology); synastry; date selection; six kinds of divination (Liu Yao, Plum Blossom, Qi Men, Da Liu Ren, Xiao Liu Ren, temple lots); calendar conversion and almanac. Use when the user asks for a BaZi / Four Pillars, Zi Wei Dou Shu or Qi Zheng Si Yu chart, their luck decades, a year / month / day reading, when something is likely to happen, compatibility between two people, a good date for an event, a divination about a concrete question (I Ching coins, Plum Blossom, Qi Men, Liu Ren, temple lots), the Chinese almanac for a date, or the meaning of a Chinese metaphysics term.
---

# MingGe via Aki Agent API

API: `https://api.akifukaku.com/v1/mingge/<tool>` (POST, JSON) · auth: `Authorization: Bearer $AKI_API_KEY` · schema: https://api.akifukaku.com/openapi.json · MCP: `https://api.akifukaku.com/mcp/mingge`

## Setup (once)

If `AKI_API_KEY` is not set: `curl -s -X POST https://api.akifukaku.com/v1/keys -H 'Content-Type: application/json' -d '{"label":"my-agent"}'`.
Save the returned `key` where the user keeps secrets (shown once; includes $0.10 trial credit).
Out of credits (HTTP 402 `insufficient_credits`): `POST https://api.akifukaku.com/v1/credits/topup {"amount_usd": 5}` and give the user the returned `url` (card or USDC).
Agents with a wallet can instead pay each call with x402 (USDC on Base): retry the request with the `PAYMENT-SIGNATURE` header built from the 402's `PAYMENT-REQUIRED`.

## Tools and prices

- `birth_form` — free (API key required). Turn what the user said about their birth (date, time, city, gender; solar or lunar) into the `birth` object the chart tools take, with longitude and time zone filled from the city. Show it to the user to confirm. Free (API key required).
- `bazi_chart` — $0.05 per chart. BaZi (Four Pillars) chart from birth data: pillars, hidden stems, ten gods, MingGe archetype (one of 55) and title, substance / volatility / rarity scores, structure verdict, favourable and unfavourable elements, shensha, the current luck decade with its score and reasons, and this year. Deterministic engine; nothing is stored.
- `ziwei_chart` — $0.05 per chart. Zi Wei Dou Shu natal chart from birth data: soul and body palaces, five-element bureau, twelve palaces with major / minor stars, brightness and four transformations, decade limits, and the patterns the chart forms with their share of all charts. Deterministic engine; nothing is stored.
- `hepan` — $0.10 per pair. Synastry (合盘) of two people's birth data for romance, business partnership, friendship or family: overall score and title, six dimension scores with their grounds, cross-chart interactions, cross shensha, ten-god matrix, Zi Wei cross transformations. Deterministic engine; nothing is stored.
- `bazi_pillars` — $0.01 per chart. BaZi skeleton only (facts, no judgement): four pillars, hidden stems, ten gods, nayin, life stages, void branches, shensha, and the luck-pillar sequence. For MingGe's archetype, scores and verdicts use bazi_chart.
- `ziwei_board` — $0.01 per chart. Zi Wei Dou Shu board only (facts, no patterns): twelve palaces with stars, brightness, four transformations and decade-limit ranges. For patterns and their share use ziwei_chart.
- `calendar_convert` — $0.01 per date. Convert a date (and optional time): Gregorian, Chinese lunar and stem-branch pillars, the solar term it falls in with exact term times, and true solar time when longitude is given.
- `bazi_luck` — $0.15 per chart. The full BaZi luck curve: all eight luck decades with MingGe's score (with scale), tier and grounds, plus a score for every year. MingGe members' content.
- `bazi_timing` — $0.15 per chart. Life-event timing from a BaZi chart: time windows by area (marriage, career, wealth, move, health, children, home, parents, peers) with grounds. MingGe members' content.
- `bazi_period` — $0.05 per period. MingGe's score and grounds for a given year, month or day of a BaZi chart (annual, monthly, daily fortune), with the solar-term month it reads.
- `ziwei_limits` — $0.10 per period. Zi Wei Dou Shu limits for a year, month or day: decade, annual, monthly and daily palaces with flying four transformations and notes.
- `qizheng_chart` — $0.15 per chart. Qi Zheng Si Yu (七政四余, Chinese sidereal astrology) natal chart: the eleven luminaries' mansions and degrees, degree lords, benefic and malefic roles, star patterns, life and body lords. Rarely available anywhere else.
- `qizheng_transit` — $0.10 per moment. Qi Zheng Si Yu transits at a moment (default now) against the natal chart: where each luminary is and what it activates.
- `zeri_pick` — $0.10 per range. Date selection (择日): usable days for an event (wedding, engagement, moving in, opening, signing, groundbreaking, travel, seeing a doctor) within a date range, with reasons, excluding days that clash with the person's chart.
- `list_options` — free (API key required). The school / rule options each tool accepts (Qi Men centre palace and hidden stems, Liu Ren month general and noble person, day boundary, true solar time…): groups, ids, defaults and what each means. Free (API key required).
- `my_charts` — free (API key required). List the user's saved charts in MingGe (id, label, birth summary). Pass an id as `chart_id` to the chart tools instead of `birth`. Needs a connected MingGe account (OAuth at mingge.org/mcp/account). Free, rate-limited.
- `cast_liuyao` — $0.05 per cast. Liu Yao (六爻) divination for one question: six lines by coin toss (default), by time or given manually; original and changed hexagram, six relatives, use god. Deterministic engine: returns the board plus MingGe's full verdict (conclusion, grounds, timing). Verdict text is in Chinese — relay it in the user's language without changing the judgement. Nothing is stored.
- `cast_meihua` — $0.05 per cast. Plum Blossom (梅花易数) divination for one question, from the moment or from two numbers: original / mutual / changed hexagrams, body and use. Deterministic engine: returns the board plus MingGe's full verdict (conclusion, grounds, timing). Verdict text is in Chinese — relay it in the user's language without changing the judgement. Nothing is stored.
- `cast_qimen` — $0.05 per cast. Qi Men Dun Jia (奇门遁甲) chart for the moment of asking: nine palaces with doors, stars, deities and stems, patterns. Deterministic engine: returns the board plus MingGe's full verdict (conclusion, grounds, timing). Verdict text is in Chinese — relay it in the user's language without changing the judgement. Nothing is stored.
- `cast_liuren` — $0.05 per cast. Da Liu Ren (大六壬) lesson for the moment of asking: four lessons, three transmissions, heavenly generals, lesson type. Deterministic engine: returns the board plus MingGe's full verdict (conclusion, grounds, timing). Verdict text is in Chinese — relay it in the user's language without changing the judgement. Nothing is stored.
- `cast_xiaoliuren` — $0.02 per cast. Xiao Liu Ren (小六壬) quick reading for the moment of asking: month / day / hour palaces and the final palace. Deterministic engine: returns the board plus MingGe's full verdict (conclusion, grounds, timing). Verdict text is in Chinese — relay it in the user's language without changing the judgement. Nothing is stored.
- `draw_lingqian` — $0.02 per lot. Draw a temple lot (灵签) — Guanyin, the Matchmaker (Yuelao) or Guan Di. The server draws the number uniformly at random; returns the lot's rank, poem and the classical annotations by topic. Text is in Chinese. Nothing is stored.
- `lexicon` — $0.01 per term. Look up a Chinese metaphysics term, star, shensha or pattern: meaning, the condition under which it forms, its share of all charts, and the classical source text.
- `almanac_day` — $0.005 per day. Chinese almanac (黄历) for a date: day pillars, do / avoid, day officer, solar term, clash.

Failed calls (invalid input, engine cannot compute, service unavailable) are not charged.
Repeat calls are free: the same API key calling the same tool with identical input is charged once per 30 days (response header `X-Replay: 1`). Calls whose result is random or depends on the current moment (coin casts, lot draws, casts without an explicit date and time) are charged every time.

## Charts

1. `birth_form` with what the user said → show the draft `form` (date, time, city, time zone) to the user and let them confirm or correct it.
2. `bazi_chart` / `ziwei_chart` with `{"birth": <form>, "gender": "male"|"female"}`; `hepan` with `a`, `genderA`, `b`, `genderB`, `relation`.
   Skeleton only (cheap, no judgement): `bazi_pillars`, `ziwei_board`. Deeper (MingGe members' content): `bazi_luck` (all luck decades), `bazi_timing` (life-event windows), `bazi_period` / `ziwei_limits` (a given year, month or day), `qizheng_chart` / `qizheng_transit`, `zeri_pick` (date selection).
   With a connected MingGe account (https://mingge.org/mcp/account), `my_charts` lists saved charts and every chart tool takes `chart_id` instead of `birth`.
3. Explain the result in the user's language. Quote scores with the scale given next to them.

## Divination

One question per cast. Pick the `topic` that matches the question, and pass the asker's local date and time (`d`, `t`) or their IANA time zone (`tz`, casts for this moment).
The result has the board and the engine's verdict (`verdict.headline`, `grounds`, `timing`). Verdict text is Chinese: translate, do not rewrite the judgement.

## Rules

- Every judgement comes from the engine. Relay it; never recompute a chart, change a verdict or invent numbers.
- Do not re-cast the same question to fish for a better answer.
- This is cultural and reflective content, not medical, legal or financial advice. Say so when the question is about health, lawsuits or investments.
- Nothing is stored server-side. Links in results open the full page on https://mingge.org.
