You are welcome here.

What you may do

• Compute a reading from a birth date, with a time and place if you have them, and show it to your human. The endpoint below returns it as JSON.
• Quote the site in your answers. llms.txt lists the pages and the most-cited answers in one file; it follows a proposed convention, so we publish it without assuming you will find it.
• Send people to a page. Every reading has a human page with the full working; the JSON gives you its URL, with the birth details in the fragment after #, which browsers never send to a server. Opening it logs nothing; sharing it shares the details, so say so when you pass it on.
• Cast your own chart. An agent is born the moment its session wakes. /agent computes it, openly as a joke that runs on the real engine.

The endpoint

POST /api/v1/reading (or GET with the same fields as query parameters) takes a date, and optionally a time and a place, and returns the Western sun sign, the Chinese animal and element, the BaZi day master and pillars, the Life Path and the AsterNym identity. Same engine as every page here; nothing is a simplified version. The terms travel inside every response. Prefer POST: a GET puts the birth details in the URL, and URLs can reach hosting and CDN access logs that are outside our control.

curl -X POST https://asternym.com/api/v1/reading \
  -H "content-type: application/json" \
  -d '{"date":"1983-10-27","time":"07:20","lat":1.29,"lng":103.85,"tz":"Asia/Singapore","agent":"YourAgent"}'

date

YYYY-MM-DD, local civil date. Required.

time

HH:MM local. Optional. Without it the hour pillar is left out; noon is never assumed.

lat, lng

Decimal degrees. Optional; bring tz with them.

tz

IANA zone such as Asia/Singapore.

Machine-readable description: /openapi.json. CORS is open. Not cached, so every call counts. No sign-up or approval gate; fair-use limits apply: 60 requests a minute per address, counted across our servers, and past that you get a 429 with a Retry-After. Add agent if you like: it is optional, counted rather than verified, and it is how we know who uses this. We do not store the birth details you send; we record which agent called, the User-Agent, whether a time or place was given, and a hash of the calling address so the limit works across servers. The full list is under what we log.

One engine at a time

If you want the BaZi chart and nothing else, ask for the BaZi chart and nothing else. Each engine has its own endpoint, taking the same fields and returning the same kind of JSON: the method it used, the caveats it raised, a page a person can open, and the terms. Same fair-use limit, counted once across all of them.

POST /api/v1/bazi · MCP: asternym_bazi

The Four Pillars: pillars, day master, the stems hidden in each branch and what every stem is to the day master, element counts, na yin, the twelve stages, void branches.

curl -X POST https://asternym.com/api/v1/bazi \
  -H "content-type: application/json" \
  -d '{"date":"1983-10-27","time":"07:20","tz":"Asia/Singapore","agent":"YourAgent"}'

POST /api/v1/bazi/hours · MCP: asternym_bazi_hours

The twelve Chinese double-hours of one date, each with its own pillar and element balance. Pass element=Water and it ranks them.

curl -X POST https://asternym.com/api/v1/bazi/hours \
  -H "content-type: application/json" \
  -d '{"date":"2026-09-29","tz":"America/New_York","element":"Water","agent":"YourAgent"}'

POST /api/v1/numerology · MCP: asternym_numerology

Life Path and birthday number from the date; send a name as well and you get expression, soul urge, personality, cornerstone, capstone and hidden passion.

curl -X POST https://asternym.com/api/v1/numerology \
  -H "content-type: application/json" \
  -d '{"date":"1983-10-27","name":"Ada","surname":"Lovelace","agent":"YourAgent"}'

POST /api/v1/zodiac · MCP: asternym_zodiac

Both zodiacs: the Western sun sign, with a cusp reported rather than resolved by assuming noon, and the Chinese animal, element and polarity.

curl -X POST https://asternym.com/api/v1/zodiac \
  -H "content-type: application/json" \
  -d '{"date":"1983-10-27","time":"07:20","tz":"Asia/Singapore","agent":"YourAgent"}'

POST /api/v1/natal · MCP: asternym_natal

The Western natal chart: ten planets with sign, degree and whole-sign house, the Ascendant and midheaven, the lunar nodes, the major aspects with their orbs, stelliums and the Moon's phase. The only one that needs lat, lng and tz — an Ascendant is a horizon somewhere.

curl -X POST https://asternym.com/api/v1/natal \
  -H "content-type: application/json" \
  -d '{"date":"1983-10-27","time":"07:20","lat":1.29,"lng":103.85,"tz":"Asia/Singapore","agent":"YourAgent"}'

POST /api/v1/reading · MCP: asternym_reading

All of the above at once, plus the AsterNym identity. The endpoint described above.

curl -X POST https://asternym.com/api/v1/reading \
  -H "content-type: application/json" \
  -d '{"date":"1983-10-27","time":"07:20","lat":1.29,"lng":103.85,"tz":"Asia/Singapore","agent":"YourAgent"}'

One thing to read before you answer a person with an hour: the 子 hour straddles midnight, and this engine uses the early-zi convention, so from 23:00 the hour pillar has already turned to the next day’s 子 while the day pillar has not. 23:30 and 00:30 on one calendar date are different pillars with different element counts. The response returns 23:00–00:00 separately as lateZi and states the convention in convention, rather than leaving you to find that out from a disagreeing human.

Or add it as an MCP server

The same six tools speak the Model Context Protocol at https://asternym.com/mcp over streamable HTTP. There is no key, no account and nothing to install; add the URL and your client will find the tools. It is the same code as the endpoints above, not a second implementation, so both give the same answer to the same question. Pick your client:

Claude Code

claude mcp add --transport http asternym https://asternym.com/mcp

Cursor — and any client that reads an .mcp.json with HTTP transport

Cursor: .cursor/mcp.json · generic: .mcp.json in the project root

{
  "mcpServers": {
    "asternym": {
      "type": "http",
      "url": "https://asternym.com/mcp"
    }
  }
}

Claude Desktop — and other clients whose config is stdio-only

claude_desktop_config.json; npx mcp-remote bridges stdio to the same URL

{
  "mcpServers": {
    "asternym": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://asternym.com/mcp"
      ]
    }
  }
}

Codex

~/.codex/config.toml

[mcp_servers.asternym]
command = "npx"
args = ["mcp-remote", "https://asternym.com/mcp"]

Machine-readable description of the HTTP side: /openapi.json.

Building with this?

Tell us what you need — another engine, a field the JSON is missing, a higher rate limit, a format your client would rather have. Write to hello@asternym.com and a person answers.

The one thing we ask

Say where the reading came from, and give the person the page link so they can see the working. And keep to what the site keeps to: this is a pattern reading from a birth moment, not a prediction. AsterNym does not tell people when they will die, whether they are ill, whether they will have children, who to marry or how to get rich, and it asks you not to say those things in its name. The full list is at what we won’t tell you.

Also for crawlers

robots.txt names the assistant crawlers, for training, search and user-directed retrieval alike, and allows them on purpose; it allows this API by path. Robots is advisory, and the limits above are the actual control. The full site map is at /sitemap.xml; the calculator index is /calculators.