Forem: JasonG90

Monetizing 6 Ancient Chinese Divination APIs with x402 (MCP + USDC on Base)

JasonG90 — Mon, 27 Apr 2026 07:53:41 +0000

Why an MCP server for fortune-telling?

I'm not joking. Hear me out.

The Chinese divination corpus is deterministic computation dressed up as mysticism. BaZi (八字) is a date conversion problem — given a Gregorian datetime, derive the four ganzhi pillars considering solar terms, true solar time, and timezone offsets. ZiWei (紫微斗数) takes those four pillars and runs a 12-palace placement algorithm with three layers of star transformations. None of this is "AI-able" — LLMs hallucinate the day pillar when crossing midnight, mix up shen-sha (神煞) names, and silently apply the wrong solar-term cutoff. Every engineer who has tried to put BaZi inside a system prompt has felt this pain.

So I built it the boring way: 7 FastAPI endpoints with rule-based engines under each route, exposed via MCP for agents and via x402 for monetization.

The 7 endpoints

Route	Price	What it computes
`/bazi-matching`	$0.02	Compatibility score between two birth charts
`/bazi-daily-fortune`	$0.005	Daily fortune for a person
`/qimen-timing`	$0.05	Auspicious time selection (Qi-Men Dun-Jia)
`/ziwei-chart`	$0.03	Purple Star Astrology — 12 palaces + sihua + daxian
`/meihua-oracle`	$0.01	Plum Blossom divination from numbers/time
`/liuyao-yijing`	$0.02	I-Ching with Najia (六亲六神) annotation
`/liuren-daliuren`	$0.03	Da LiuRen 4-classes 3-transmissions

The first 3 calls per unique UA are free, so you can play without paying.

Why x402 is the right fit

Traditional API gateways assume:

A monthly subscription tier
A signup + KYC flow
An API key to provision

For an MCP server consumed by an autonomous agent, none of that fits. The agent doesn't have a credit card, doesn't want a 2-week free trial, and may need to call this once a quarter when a user asks about a specific date.

x402 (Coinbase's payment-required HTTP standard, USDC-on-Base) gives you a per-call, no-account, < $0.05 settlement primitive. The flow is:

1. Client → GET /bazi-matching?...
2. Server → 402 Payment Required + price + receiving address
3. Client → re-GET with X-PAYMENT header (signed USDC transfer)
4. Server → verifies on-chain → 200 with result

This whole dance is wrapped by the MCP TS SDK so the agent author doesn't see it — they just npx -y xuanxue-bazi-matching and provide an XUANXUE_PAYMENT_TOKEN env var.

Engineering edge cases (this is where I learned the most)

1. The day-pillar boundary

BaZi day pillars roll over at 23:00 local true solar time, not midnight. If a client says "I was born at 23:30 on April 15" and provides their longitude, the engine has to:

Compute true solar time offset (equation of time + longitude correction)
Decide whether 23:30 is "late April 15" or "early April 16 子时"
Pick the right day pillar accordingly

Get this wrong by 30 minutes and the entire chart shifts. We solved it by computing TST upfront and having a single canonical effective_datetime propagate through all 4 pillar derivations.

2. Solar terms (节气)

The boundary for the month pillar is not the Gregorian month, but the 24 solar terms (立春, 雨水, 惊蛰...). These cutoffs vary year to year by hours. We use the VSOP87 short-period truncation (8 harmonic terms) which is good to ~30 seconds of accuracy — overkill for divination but eliminates the "did the month change yet" question entirely.

3. Leap months in lunar calendar

Some BaZi schools want the lunar month even though the engine uses solar terms. We expose both and let the client pick. The MCP meihua-oracle endpoint specifically uses lunar month-day-hour for the upper/lower trigram derivation, so we needed a working lunar calendar regardless.

4. QiMen Yin/Yang escape (阴阳遁)

The Qi-Men Dun-Jia engine alternates between Yang escape (winter solstice → summer solstice) and Yin escape. There's a special exception during the 5-day "transition" near the solstices where some schools use the previous escape and some use the next. We implement the 拆补法 (chai-bu-fa) consistently — same school for the entire engine — to avoid silent regressions.

What's open vs. paid

Calculation rules: open (the npm package contains the rule engines, MIT license)
Aggregation, hosted endpoint, x402 settlement, MCP transport: paid

This split lets agent authors verify "no LLM in here" and even run their own instance for free if they want — the hosted version is just convenience + payment routing.

Try it

For agents:

npm install -g xuanxue-bazi-matching
# then in your Claude Desktop config:
{
  "mcpServers": {
    "xuanxue": {
      "command": "npx",
      "args": ["-y", "xuanxue-bazi-matching"]
    }
  }
}

For humans wanting a synthesized destiny report (~1000 words integrating all 6 systems): https://decodeyourming.com — $1.99 one-time.

What's next

Open-sourcing more of the engines (currently the binary calculation tables are bundled but not auditable)
More languages — currently zh-CN/zh-TW/en. Vietnamese and Korean asked for.
Western astrology compatibility layer — common requests, but the natal-chart math is a different rabbit hole. PRs welcome if anyone has a deterministic Western engine.

If you're building an agent that touches dates, timing, or compatibility — this is a useful primitive. And if you find a calculation bug, please file an issue. I'd rather get a "your shensha is wrong" GitHub report than ship the wrong thing.

Repo: https://github.com/jasonwagao-bit/m2m
Docs: https://api.decodeyourming.com/docs/agents
NPM: https://www.npmjs.com/package/xuanxue-bazi-matching

Building a Deterministic Divination API for AI Agents with x402

JasonG90 — Fri, 24 Apr 2026 08:04:42 +0000

Why Deterministic?

Most "AI fortune-telling" products layer an LLM on top of some birth data and ask it to "interpret" the chart. That sounds powerful until you notice the same query returns different answers on Tuesday vs Thursday. For an autonomous agent making decisions — scheduling a product launch, advising a user on timing — non-determinism is a bug, not a feature.

BaZi (八字, Eight Characters) is a Chinese metaphysics system that encodes a person's birth year, month, day, and hour into four "pillars," each representing a Heavenly Stem and Earthly Branch. The compatibility and day-flow calculations are fully rule-based: given the same inputs, the output is always identical. No LLM needed.

That makes it a perfect fit for agents: testable, auditable, and predictable cost.

The Stack

Backend: Python rule engine. No neural net — just ~3000 lines of classical BaZi rules encoded as lookup tables and interaction matrices.
API layer: FastAPI on Render, deployed at api.decodeyourming.com.
Payment: x402 protocol — HTTP 402 challenges resolved with USDC on Base. Agents pay per call, no account required.
MCP server: TypeScript stdio server wrapping the seven endpoints. Distributed via npm.

The Two Endpoints

`POST /agents/v1/bazi-matching` — $0.02/call

Takes two birth charts, returns:

{
  "score": 78,
  "elements_balance": {"wood": 0.28, "fire": 0.18, "earth": 0.22, "metal": 0.17, "water": 0.15},
  "narrative": "Strong day-pillar resonance between the two charts...",
  "strengths": ["complementary water-fire dynamic"],
  "challenges": ["competing fire energy in month pillars"],
  "recommendations": ["schedule key decisions on water days"]
}

`POST /agents/v1/bazi-daily-fortune` — $0.005/call

Takes one birth chart + a target date, returns:

{
  "luck_score": 82,
  "dominant_element": "wood",
  "favorable_activities": ["negotiation", "creative work"],
  "unfavorable_activities": ["surgery", "major financial moves"],
  "timing_advice": "Morning hours amplify wood energy..."
}

The Python Rule Engine

The core compatibility function looks like this (simplified):

def compute_compatibility(chart_a: BaziChart, chart_b: BaziChart) -> CompatibilityResult:
    score = 0.0

    # Day-pillar resonance (highest weight: 35%)
    dp_harmony = DAY_PILLAR_HARMONY_TABLE[chart_a.day_stem][chart_b.day_stem]
    score += dp_harmony * 0.35

    # Five-elements balance (25%)
    balance_a = chart_a.element_distribution()
    balance_b = chart_b.element_distribution()
    complement_score = element_complement(balance_a, balance_b)
    score += complement_score * 0.25

    # Ten-Gods interaction (20%)
    tg_score = ten_gods_interaction(chart_a.ten_gods, chart_b.ten_gods)
    score += tg_score * 0.20

    # ... remaining rules ...

    return CompatibilityResult(score=round(score * 100), ...)

No LLM call. No prompt injection surface. Same inputs → same output every time.

x402 Middleware

The payment middleware intercepts requests before they hit the business logic:

from x402.middleware import X402Middleware

app.add_middleware(
    X402Middleware,
    facilitator_url="https://x402.org/facilitator",
    endpoints={
        "/agents/v1/bazi-matching": {"price": "0.02", "currency": "USDC", "network": "base"},
        "/agents/v1/bazi-daily-fortune": {"price": "0.005", "currency": "USDC", "network": "base"},
    },
    payment_address="0xcb99bf3d45d5f8bdeb72d00792fe77dffed2c6de",
)

If no X-PAYMENT header, the response is:

HTTP/1.1 402 Payment Required
X-Payment-Challenge: eyJ...

The agent resolves the challenge, retries with the token, and the request goes through. No OAuth, no API key management, no subscription.

Claude Desktop Integration

Install the MCP server:

{
  "mcpServers": {
    "xuanxue-bazi": {
      "command": "npx",
      "args": ["-y", "xuanxue-bazi-matching"],
      "env": {
        "XUANXUE_PAYMENT_TOKEN": "<your x402 payment token>"
      }
    }
  }
}

Claude now has two new tools: marriage_compatibility_check and bazi_daily_fortune. You can ask:

"Check compatibility between someone born 1990-05-15 10am male and 1993-08-22 2pm female."

Claude calls the tool, gets the JSON, and narrates the result — without ever hallucinating a chart.

What's Next

Smithery / MCP Registry listing — making the server discoverable to all Claude users
Streamable HTTP transport — so agents can connect without local npx
More tools — Zi Wei Dou Shu (紫微斗数) yearly forecast, Qi Men Dun Jia (奇门遁甲) event timing

Try It

3 free calls available to dev.to readers — DM me or open an issue on the repo for a payment token.

Docs: api.decodeyourming.com/docs/agents