I-Ching

The I-Ching (Book of Changes) is an ancient Chinese divination system using 64 hexagrams. Each hexagram is a stack of six lines (solid or broken) that represents a life situation with guidance for action. Your users care about this for oracle apps, daily guidance, and decision-making tools.

New to fetch()? The Western Astrology guide has an annotated example explaining every line of an API call.

What you can build

• Oracle apps — cast a hexagram reading with changing lines
• Daily guidance features — daily hexagram with interpretation
• Decision-making tools — ask a question, receive I-Ching wisdom
• Reference apps — browse and search all 64 hexagrams and 8 trigrams

Which endpoints to call

Daily hexagram

One call, returns today's hexagram with full interpretation:

const response = await fetch('https://roxyapi.com/api/v2/iching/daily', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({})
});
const daily = await response.json();

Response:

{
  "date": "2026-03-15",
  "seed": "2026-03-15",
  "hexagram": {
    "number": 11,
    "symbol": "䷊",
    "chinese": "泰",
    "english": "Peace",
    "pinyin": "tai",
    "upperTrigram": { "english": "Earth" },
    "lowerTrigram": { "english": "Heaven" },
    "judgment": "Peace. The small departs, the great approaches...",
    "image": "Heaven and Earth unite: the image of Peace...",
    "interpretation": {
      "general": "A time of harmony, growth, and favorable conditions...",
      "love": "Relationships flourish under mutual understanding...",
      "career": "Professional endeavors gain momentum...",
      "decision": "Conditions favor action. Move forward with confidence...",
      "advice": "Use this period of harmony wisely..."
    }
  },
  "dailyMessage": "Your hexagram for today: Peace..."
}

Which fields to show your users: hexagram.english ("Peace") and hexagram.symbol for the visual. hexagram.interpretation.general is the main reading. love, career, decision, and advice are category breakdowns. dailyMessage is a ready-made one-liner for notifications or widgets.

Cast a reading

Generates a full reading with changing lines. Changing lines transform one hexagram into another, showing the situation's movement:

const response = await fetch('https://roxyapi.com/api/v2/iching/cast', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const reading = await response.json();
// reading.hexagram — the primary hexagram
// reading.changingLinePositions — which lines are changing (e.g., [2, 5])
// reading.resultingHexagram — what the hexagram transforms into

Which fields to show your users: Show the primary hexagram with its interpretation. If changingLinePositions is not empty, show which lines are changing and display the resultingHexagram as the "outcome" — this is the narrative arc of the reading.

Hexagram lookup

Look up any of the 64 hexagrams by number:

const response = await fetch('https://roxyapi.com/api/v2/iching/hexagrams/1', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const hexagram = await response.json();
// hexagram.english — "The Creative"
// hexagram.judgment, hexagram.image, hexagram.interpretation

Full API reference

See all I-Ching endpoints in the API Reference.