asktian-sdk
Advanced tools
TypeScript SDK for the askTIAN Metaphysics API — 64 endpoints across 7 traditions (Chinese, Western, Indian, African, Islamic, Japanese, Korean)
Official JavaScript/TypeScript SDK for the askTIAN Metaphysics API — 37 divination traditions, 49 endpoints including Qimen Dunjia, Jyotish, Ifá, Mahabote, 十二宮 Twelve Palaces, Tarot, Runes, Numerology, and TIAN Blended synthesis endpoints.
npm install asktian-sdk
# or
pnpm add asktian-sdk
# or
yarn add asktian-sdk
import { AskTianClient } from "asktian-sdk";
const client = new AskTianClient({ apiKey: "at_live_your_key_here" });
// Qimen Dunjia
const reading = await client.qimen.calculate({
date: "2026-03-19",
time: "10:00",
question: "Should I sign the contract today?",
});
// Mahabote (Burmese Astrology) — new in v1.5.0
const mahabote = await client.mahabote.calculate({
birthDate: "1990-01-15",
question: "What does my birth planet reveal about my career?",
});
// Wednesday PM births → Rahu planet
const rahuReading = await client.mahabote.calculate({
birthDate: "1990-03-14",
isPM: true,
question: "What challenges should I prepare for?",
});
// 十二宮 Twelve Palaces (Guiguzi Palace Destiny) — new in v1.6.0
const twelvePalaces = await client.twelvepalaces.calculate({
birthYear: 1990,
birthMonth: 3,
birthDay: 15,
birthHour: 10,
question: "What does my palace destiny reveal about my fortune?",
});
// twelvePalaces.palace → 9
// twelvePalaces.degree → 0
// twelvePalaces.fortuneTitle → "智慧之命"
// twelvePalaces.poem → classical 4-line verse
// twelvePalaces.marriage → marriage reading
// twelvePalaces.wealth → wealth reading
// TIAN Global — cross-civilisational synthesis across all 5 traditions
const global = await client.tian.global({
birthdate: "1990-01-15",
birthTime: "06:30",
birthPlace: "Singapore",
question: "Should I launch my business this quarter?",
});
// v1.8.0: signProfile and compatProfile returned directly
// global.signProfile?.mantra → "I Use"
// global.signProfile?.majorArcana → "The Devil"
// global.compatProfile?.loveDimensionLabel → "Positive"
| Interface | Endpoint | Field | Since |
|---|---|---|---|
ChineseZodiacProfile | almanac.zodiacSign | chineseProfile | v1.7.0 |
HoroscopeSignProfile | almanac.zodiacSign | westernProfile | v1.7.0 |
HoroscopeSignProfile | horoscope.calculate | signProfile | v1.7.0 |
CompatDimension | (used inside ZodiacDimensions / HoroscopeDimensions) | — | v1.7.0 |
ZodiacDimensions | compatibility.zodiac | dimensions | v1.7.0 |
ZodiacDimensions | compatibility.birthday | dimensions | v1.7.0 |
HoroscopeDimensions | compatibility.birthday | horoscopeDimensions | v1.7.0 |
TianGlobalSignProfile | tian.global | signProfile | v1.8.0 |
TianGlobalCompatProfile | tian.global | compatProfile | v1.8.0 |
TianGlobalDoneEvent | tian.global stream | done event (extended) | v1.9.0 |
TianGlobalStreamChunk | tian.global stream | full event union | v1.9.0 |
ZodiacCompatResponse | compatibility.zodiac | full response | v2.0.0 |
BirthdayCompatResponse | compatibility.birthday | full response | v2.0.0 |
AlmanacZodiacResponse | almanac.zodiacSign | full response | v2.0.0 |
HoroscopeResponse | horoscope.calculate | full response | v2.0.0 |
DivinationHolyMeaning | divination.draw | holyMeaning oracle map | v2.1.0 |
DivinationDrawResponse | divination.draw | full response | v2.1.0 |
AlmanacDailyResponse | almanac.daily | full response with 黃曆 fields | v2.2.0 |
Since v1.7.0, several endpoints return enriched profile data sourced from the YouApp dataset.
import type {
ChineseZodiacProfile,
HoroscopeSignProfile,
CompatDimension,
ZodiacDimensions,
HoroscopeDimensions,
TianGlobalSignProfile,
TianGlobalCompatProfile,
} from "asktian-sdk";
// almanac.zodiacSign — 60-element Chinese zodiac profile + Western sign profile
const zodiac = await client.almanac.zodiacSign({ birthDate: "1990-01-15" });
const chinese: ChineseZodiacProfile | null = zodiac.chineseProfile;
// chinese?.personality, chinese?.strengths, chinese?.career, chinese?.love
const western: HoroscopeSignProfile | null = zodiac.westernProfile;
// western?.mantra, western?.majorArcana, western?.medical, western?.herbalAllies
// compatibility.zodiac — 5-dimension Chinese zodiac compatibility
const compat = await client.compatibility.zodiac({ animal1: "rat", animal2: "dragon" });
const dims: ZodiacDimensions | null = compat.dimensions;
// dims?.love.label → "Positive"
// dims?.love.text → full description
// dims?.career, dims?.wealth, dims?.health, dims?.marriage
// horoscope.calculate — Western sign profile on the sun sign
const horoscope = await client.horoscope.calculate({ birthdate: "1990-01-15" });
const profile: HoroscopeSignProfile | null = horoscope.signProfile;
// profile?.mantra, profile?.majorArcana, profile?.bodyParts, profile?.symbolism
// tian.global — signProfile and compatProfile at the top level (v1.8.0+)
const g = await client.tian.global({ birthdate: "1990-01-15", ... });
const sp: TianGlobalSignProfile | null = g.signProfile;
// sp?.westernSign → "capricorn", sp?.mantra → "I Use", sp?.majorArcana → "The Devil"
const cp: TianGlobalCompatProfile | null = g.compatProfile;
// cp?.chineseAnimal → "rat", cp?.partnerAnimal → "dragon", cp?.loveDimensionLabel → "Positive"
Use TianGlobalStreamChunk for a fully typed for await loop over the tian.global stream. The stream yields four event types: system (per-tradition result), synthesis_chunk (LLM token), done (final result with signProfile + compatProfile), and error.
import { AskTianClient } from "asktian-sdk";
import type { TianGlobalStreamChunk } from "asktian-sdk";
const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });
let synthesis = "";
for await (const event of client.tian.global.stream({
birthdate: "1990-01-15",
birthTime: "06:30",
birthPlace: "Singapore",
question: "Should I launch my business this quarter?",
}) as AsyncGenerator<TianGlobalStreamChunk>) {
if (event.type === "system") {
// Each tradition result arrives progressively
console.log(`[${event.name}] score: ${event.score}`);
}
if (event.type === "synthesis_chunk") {
process.stdout.write(event.chunk);
synthesis += event.chunk;
}
if (event.type === "done") {
console.log("\nBlended score:", event.blendedScore);
console.log("Mantra:", event.signProfile?.mantra);
console.log("Tarot archetype:", event.signProfile?.majorArcana);
console.log("Love label:", event.compatProfile?.loveDimensionLabel);
}
}
Type cast note:
client.tian.global.stream()returnsAsyncGenerator<TianStreamEvent>at the base type level. Cast toAsyncGenerator<TianGlobalStreamChunk>to access the typedsignProfileandcompatProfilefields on thedoneevent.
| Method | System |
|---|---|
client.qimen.calculate(input) | Qimen Dunjia 奇門遁甲 |
client.liuyao.calculate(input) | Liu Yao 六爻 |
client.meihua.calculate(input) | Meihua Yishu 梅花易數 |
client.daliu.calculate(input) | Da Liu Ren 大六壬 |
client.xiaoliu.calculate(input) | Xiao Liu Ren 小六壬 |
client.taiyi.calculate(input) | Tai Yi Shen Shu 太乙神數 |
client.nameAnalysis.analyze(input) | Chinese Name Analysis 姓名學 |
client.compatibility.calculate(input) | BaZi Compatibility 八字合婚 |
client.auspicious.analyze(input) | Auspicious Numbers 吉祥數字 |
client.almanac.get(input) | Chinese Almanac 通書 |
client.divination.draw(input) | Divination Lots 求籤 |
client.astrology.calculate(input) | Chinese Astrology 紫微斗數 |
client.mahabote.calculate(input) | Mahabote မဟာဘုတ် (Burmese Astrology) |
client.twelvepalaces.calculate(input) | 十二宮 Twelve Palaces 鬼谷子命宮 |
| Method | System |
|---|---|
client.tarot.draw(input) | Tarot |
client.coinFlip.flip(input) | Coin Flip Oracle |
client.runes.cast(input) | Norse Runes |
client.numerology.calculate(input) | Numerology |
client.zodiac.calculate(input) | Western Zodiac Compatibility |
client.birthday.compare(input) | Birthday Compatibility |
client.bloodtype.compare(input) | Blood Type Compatibility |
| Method | System |
|---|---|
client.jyotish.calculate(input) | Jyotish (Vedic Astrology) |
client.anka.calculate(input) | Anka Shastra (Indian Numerology) |
| Method | System |
|---|---|
client.ifa.calculate(input) | Ifá Divination |
client.vodun.calculate(input) | Vodun Oracle |
client.hakata.calculate(input) | Hakata (Bone Throwing) |
| Method | System |
|---|---|
client.rammal.calculate(input) | Ilm al-Raml (Geomancy) |
client.khatt.calculate(input) | Khatt al-Raml |
| Method | Traditions Combined |
|---|---|
client.tian.eastern(input) | All Eastern systems |
client.tian.western(input) | All Western systems |
client.tian.eastwest(input) | Eastern + Western |
client.tian.african(input) | All African systems |
client.tian.islamic(input) | All Islamic systems |
client.tian.indian(input) | All Indian systems |
client.tian.global(input) | All 5 traditions — full synthesis (29 systems) |
import { AskTianClient, AskTianError } from "asktian-sdk";
const client = new AskTianClient({ apiKey: "at_live_your_key_here" });
try {
const result = await client.qimen.calculate({
date: "2026-03-19",
time: "10:00",
question: "Should I proceed?",
});
console.log(result);
} catch (err) {
if (err instanceof AskTianError) {
console.error(`API error ${err.status}: ${err.message}`);
// err.status: HTTP status code (401, 403, 429, etc.)
// err.body: full error response body
}
}
AlmanacDailyResponse interface — types the full almanac.daily response with complete 黃曆 fields
date, lunarDate, lunarYear, lunarMonth, lunarDay, yearGanZhi, monthGanZhi, dayGanZhi, heavenlyStem, earthlyBranch, yearZodiac, dayZodiactwelveValue, twelveDeity, twelveDeityLuck, isHuangDao, naYinauspiciousActivities, inauspiciousActivitiesjiShen (吉神), xiongSha (凶煞), pengZuGan, pengZuZhi, taiShen, xiu, xiuLuck, xiuSong, liuYao, nineStarpositionCai, positionXi, positionFu, positionYangGui, positionYinGuioverallFortune, scoreclient.almanac.daily() now returns Promise<AlmanacDailyResponse> instead of Promise<unknown>client.almanac.zodiacSign() now returns Promise<AlmanacZodiacResponse> instead of Promise<unknown>DivinationHolyMeaning interface — typed map of life-domain oracle categories (聖意)
求財, 交易, 婚姻, 六甲, 自身, 疾病, 家運, 尋人, 失物, 移徙 (plus index signature for other systems)DivinationDrawResponse interface — types the full divination.draw response
lotNumber, title?, fortuneLevel?, poemText?, interpretation?, dongpoJie?, bixianZhu?, story?, holyMeaning?: DivinationHolyMeaning, score, creditsUsed?, system?client.divination.draw() now returns Promise<DivinationDrawResponse> instead of Promise<unknown>holyMeaning is currently populated for the wenshu system (100 lots); additional temple systems will be backfilled in future releasesZodiacCompatResponse interface — types the full compatibility.zodiac response
score, level, description, dimensions?: ZodiacDimensionsBirthdayCompatResponse interface — types the full compatibility.birthday response
score, romanceScore, friendshipScore, marriageScore, dimensions?, horoscopeDimensions?AlmanacZodiacResponse interface — types the full almanac.zodiacSign response
western?, chinese?, chineseProfile?: ChineseZodiacProfile, westernProfile?: HoroscopeSignProfileHoroscopeResponse interface — types the full horoscope.calculate response
sunSign, moonSign?, ascendant?, elementProfile?, placements?, synthesis?, signProfile?: HoroscopeSignProfile, creditsUsed?TianGlobalDoneEvent interface — extends TianDoneEvent with signProfile? and compatProfile?TianGlobalStreamChunk union type — typed for await loop for tian.global streamTianGlobalSignProfile interface — types signProfile returned by tian.global
westernSign: Western zodiac sign key (e.g. "capricorn")mantra: Sign mantra (e.g. "I Use")majorArcana: Major Arcana Tarot archetype (e.g. "The Devil")TianGlobalCompatProfile interface — types compatProfile returned by tian.global
chineseAnimal: Subject's Chinese zodiac animalpartnerAnimal: Partner's Chinese zodiac animalloveDimensionLabel: Love dimension label from YouApp 4D data (e.g. "Positive")ChineseZodiacProfile interface — types chineseProfile on almanac.zodiacSign
HoroscopeSignProfile interface — types westernProfile on almanac.zodiacSign and signProfile on horoscope.calculate
CompatDimension interface — single dimension with label and textZodiacDimensions interface — types dimensions on compatibility.zodiac and compatibility.birthday
CompatDimensionHoroscopeDimensions interface — types horoscopeDimensions on compatibility.birthday
client.twelvepalaces.calculate() — 十二宮 Twelve Palaces (鬼谷子命宮)
comingSoon flag for palace 14 degree entries not in the classical sourcetian.global to include 十二宮 (29 systems, 145 TIAN Points)client.mahabote.calculate() — Mahabote မဟာဘုတ် (Burmese Astrology)
planetIcons field: CDN URLs for all 8 birth planet icons (default + shiny variants)tian.global to include Mahabote (28 systems, 140 TIAN Points)client.life.boneWeight() — Chinese Bone Weight (骨重) life destiny systemclient.horoscope.calculate() — Western Horoscope (Sun/Moon/Rising + full planetary positions)tian.global to 26 systemsclient.ifa.calculate(), client.vodun.calculate(), client.hakata.calculate() — African traditionclient.rammal.calculate(), client.khatt.calculate() — Islamic traditionclient.tian.african(), client.tian.islamic() TIAN blended endpointsclient.jyotish.calculate(), client.anka.calculate() — Indian traditionclient.tian.indian() TIAN blended endpointstream() for all 7 TIAN blended endpointsVisit asktian.com → Dashboard → API Keys. Pay with $TIAN on Base network to activate a subscription plan.
MIT
FAQs
TypeScript SDK for the askTIAN Metaphysics API — 64 endpoints across 7 traditions (Chinese, Western, Indian, African, Islamic, Japanese, Korean)
We found that asktian-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GPT-6 Astra hits 100% on ExploitBench and finds zero-days autonomously, while independent tests reveal scope violations and monitoring gaps.
Product
Socket can now send alerts and supply chain attack notifications to Microsoft Teams, with filters that route the right updates to each channel.
Security News
pnpm 12 rewrites the package manager in Rust, cutting install times by up to 90% while preserving pnpm 11 workflows and lockfiles.