Saju API › Fortune Flow API

Fortune Flow API

Send one person's birth date and time, and the API calculates how the 10-year luck cycles (Daeun), annual luck (Seun) and monthly luck layer onto the natal chart, then returns as JSON the numbers for drawing a graph and a list of relations between the luck cycles and the natal chart. In Saju (Four Pillars of Destiny), the natal chart is the set of characters fixed at birth, and each luck cycle brings its own characters that interact with it. The product is called "Fortune Flow"; it handles one person per call and does not use an LLM.

Get Started guide Playground Pricing

What it returns

• Cumulative line — for 10-year luck, natal chart + 10-year luck; for annual luck, natal chart + that year's 10-year luck + annual luck; clamped to ±100 (line)
• Per-character share — the share of one luck character, split into support, control, hidden stems and root (share)
• Five role names — whether the element of that character is the chart's Yongsin (favorable), Huisin (helpful), Gisin (unfavorable), Gusin (harmful) or Hansin (neutral) element; a name, not a score (shinRole)
• Combinations, clashes and punishments — a list of relations between luck characters and natal characters, with rule IDs; they are not included in the scores (relations·triples)
• Combination release — natal combinations touched by 10-year or annual luck characters, newly formed combinations, and codes for building on-screen text (hapPulim)
• Compatibility overlay inputs — the Yongsin element and the element counts of the visible characters, used when overlaying several people (compatInputs)

How to read the vertical axis

The vertical-axis value is "the Day Master side's score with the luck characters added". It is the natal chart's strength total plus, for each luck character, a share scored with the same per-character table as the natal chart (support, control, hidden stems, root), clamped to ±100. It does not measure whether luck is good or bad. The labels strong, balanced and weak are the natal chart's own. Monthly luck has no cumulative line; it only gives that month's share (delta).

Range and monthly luck

range sets the range of annual luck (in solar-calendar years, up to 101 years). We recommend fetching from the birth year to birth year + 100 once and slicing it on screen. monthsOfYear is the Saju year for which the 12 months of monthly luck are calculated (from Ipchun, the solar term that starts spring, of that year until just before the next year's Ipchun). If omitted, it is the Saju year that the current moment (Korean time) falls in; if null, there is no monthly layer.

Birth time, gender and birthplace

Without birthTime, the hour pillar is treated as unknown, the calculation uses the remaining six characters, and hourKnown: false is added. Without gender, there is no 10-year luck layer. The birthplace fields (birthLatitude, birthLongitude, country) are the same as in the Manseryeok API and apply the same true solar time correction. Send Fortune Flow the same location you sent to Manseryeok so both results use the same natal chart.

Request example

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "calendar": "solar",
  "gender": "male",
  "timezone": "Asia/Seoul",
  "range": { "fromYear": 1990, "toYear": 2090 },
  "monthsOfYear": 2026
}

Authentication uses the X-Partner-Api-Key header, and the base URL is https://api.hrum.ai/api/v1/partners/v1. Python and JavaScript examples and error handling are in the Get Started guide.

Response example (excerpt)

{
  "success": true,
  "data": {
    "engineVersion": "saju-flow-6",
    "kbVersion": "2026.10.11-7",
    "hourKnown": true,
    "natalAmbiguous": null,
    "natal": {
      "score": -37, "result": "중화", "level": "약약",
      "breakdown": { "season": -30, "support": 36, "control": -28, "hidden": -5, "root": 5 },
      "primaryYongshin": "토",
      "shin": { "yongshin": "토", "huishin": "화", "gishin": "목", "gushin": "수", "hanshin": "금" },
      "ruleIds": ["R-SAJU-STR-001", "R-SAJU-STR-018", "R-SAJU-STR-019", "R-SAJU-YONG-170"]
    },
    "daeun": [
      { "startYear": 1997, "endYear": 2006, "startAge": 7,
        "chars": [
          { "pos": "stem", "char": "임", "hanja": "壬", "ohaeng": "수", "sipsin": "식신", "shinRole": "gushin",
            "share": { "support": 0, "control": -8, "hidden": 0, "root": 0, "total": -8 } },
          { "pos": "branch", "char": "오", "hanja": "午", "ohaeng": "화", "sipsin": "정관", "shinRole": "huishin",
            "share": { "support": 0, "control": -10, "hidden": -5, "root": 0, "total": -15 } }
        ],
        "delta": -23, "line": { "value": -60, "clamped": false },
        …

The start of the response example (the natal chart and the first 10-year luck cycle). The response with annual luck, monthly luck and combination release, and the field descriptions are in the reference.

Pricing

Fortune Flow costs ₩50 per call (excl. VAT; ₩55 incl. VAT). A wider range or monthly luck keeps the same single-call price. Only successful calls are deducted from prepaid credits; 4xx and 5xx error responses are not charged.

Store a result once you have it, and reuse it. Sending the same request again is charged again. The same birth date and time with the same options always gives the same result, so save the first response in your database (for example, keyed by a hash of the request body) and use the saved value from then on at no cost. For results that change by date, such as a daily fortune, include the date in the key and reuse the result for that day only.

Full pricing

Full reference

The full parameter table, response field descriptions and error codes are in the reference: Fortune Flow API reference. Other Saju products are listed under All Saju APIs.

Contact: contact@float.do · Operated by FLOAT Co., Ltd.