I-Ching API for Developers: Hexagrams and Book of Changes

About the author: Hiroshi Kagawa is an I-Ching Scholar and Dream Analyst with a Ph.D. in East Asian Philosophy from Kyoto University. He has researched the I-Ching as a decision-making and divination framework for 25 years, translated two classical I-Ching commentaries into modern Japanese, and teaches hexagram interpretation at Waseda University.

If you have built apps with astrology or tarot data, you already understand that ancient systems translate well into structured APIs. The I-Ching is different. Most developers have never encountered it, and the search results for "I-Ching API" return a dead npm library from 2018 and Wikipedia. No production API existed for this domain until now. This article explains what the I-Ching is, what a hexagram API returns, how the three-coin method works digitally, and how to build oracle features with working code examples.

What Is the I-Ching and Why Does It Matter for Developers?

The I-Ching, also called the Book of Changes (Yi Jing), is a 3,000 year old Chinese divination and wisdom text. It predates Confucius, who wrote commentaries on it, and remains one of the most consulted oracle systems in the world. The system is built on a binary foundation: yin (broken line) and yang (solid line). Three lines form a trigram. Two trigrams stacked together form a hexagram. There are 8 trigrams and 64 hexagrams, each representing a distinct life situation with guidance for decisions, relationships, career, and personal growth. What makes the I-Ching unique among divination systems is its concept of changing lines, where certain lines in a hexagram transform from yin to yang or vice versa, producing a second hexagram that shows how the current situation will evolve. This transformation mechanic gives the I-Ching a dynamic quality that static oracle systems lack.

How the Three-Coin Casting Method Works Digitally

The traditional I-Ching reading uses three coins tossed six times. Each toss produces a value between 6 and 9. A value of 6 (three tails) is old yin, a changing broken line. A value of 7 (two tails, one head) is young yang, a stable solid line. A value of 8 (two heads, one tail) is young yin, a stable broken line. A value of 9 (three heads) is old yang, a changing solid line. The six tosses build a hexagram from bottom to top. Changing lines (6 and 9) then flip to their opposite, creating a second "resulting" hexagram.

In a digital implementation, the challenge is reproducibility. A user who asks the same question should receive the same reading. The Roxy I-Ching API solves this with seeded randomness. Pass any string as a seed (a user ID, session token, or question hash) and the casting is deterministic. Same seed produces the same six line values, the same primary hexagram, the same changing lines, and the same resulting hexagram. Omit the seed for a truly random casting. This approach lets you build features where readings persist across sessions without storing state on your server.

Ready to build an I-Ching oracle? Roxy I-Ching API gives you 64 hexagrams, 384 changing lines, 8 trigrams, and authenticated casting with seeded reproducibility. See pricing.

What an I-Ching API Returns: Data Structure Overview

A production I-Ching API returns structured JSON covering every element a divination app needs. Here is what each data type contains.

Hexagram data includes the King Wen sequence number (1 through 64), the Unicode hexagram symbol, the original Chinese name, pinyin romanization, English translation, the upper and lower trigram names, the Judgment text (the primary oracle statement), the Image text (symbolic guidance from the trigram combination), and modern interpretations for five life areas: general, love, career, decision-making, and practical advice.

Changing line data provides interpretation text for all six line positions (bottom to top) of each hexagram. That is 384 total changing line entries across the full set. Each entry explains what it means when that specific line is a changing line in your casting.

Trigram data covers all 8 trigrams (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake) with Chinese name, pinyin, binary pattern, Five Element correspondence, family archetype, compass direction, body part, animal symbol, season, and a full meaning description.

Casting data returns the primary hexagram, the six line values (6 through 9), which positions are changing lines, and the resulting hexagram if any lines changed.

Working Code: Cast an I-Ching Reading

The casting endpoint simulates the three-coin method and returns the complete reading. All endpoints are under /api/v2/iching/.

curl -X GET "https://roxyapi.com/api/v2/iching/cast?seed=user123-question1" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "seed": "user123-question1",
  "hexagram": {
    "number": 11,
    "symbol": "䷊",
    "chinese": "泰",
    "english": "Peace",
    "pinyin": "Tai",
    "upperTrigram": "Earth",
    "lowerTrigram": "Heaven",
    "judgment": "Peace. The small departs, the great approaches. Good fortune. Success.",
    "image": "Heaven and earth unite: the image of Peace. The ruler fashions the way of heaven and earth.",
    "interpretation": {
      "general": "A period of harmony and prosperity...",
      "love": "Deep mutual understanding and emotional harmony flourish now...",
      "career": "Exceptional opportunities for advancement and collaboration...",
      "decision": "The time is right for bold action. Conditions strongly favor your plans...",
      "advice": "Embrace this harmonious period. Build partnerships and share abundance..."
    },
    "changingLines": [
      { "position": 1, "text": "When ribbon grass is pulled up, the sod comes with it..." },
      { "position": 2, "text": "Bearing with the uncultured in gentleness..." },
      { "position": 3, "text": "No plain not followed by a slope..." },
      { "position": 4, "text": "He flutters down, not boasting of his wealth..." },
      { "position": 5, "text": "The sovereign gives his daughter in marriage..." },
      { "position": 6, "text": "The wall falls back into the moat..." }
    ]
  },
  "lines": [7, 8, 9, 7, 6, 8],
  "changingLinePositions": [3, 5],
  "resultingHexagram": {
    "number": 34,
    "english": "The Power of the Great",
    "symbol": "䷡"
  }
}

The lines array shows each coin toss result (6 through 9) from bottom to top. Positions 3 and 5 are changing lines (values 9 and 6), so the reading includes a resultingHexagram showing what the situation transforms into. Your app can display both hexagrams with an arrow or transition animation between them.

Working Code: Get a Specific Hexagram

Retrieve full details for any of the 64 hexagrams by King Wen sequence number.

curl -X GET "https://roxyapi.com/api/v2/iching/hexagrams/1" \
  -H "X-API-Key: YOUR_API_KEY"

This returns the complete Hexagram 1 (The Creative / Qian) with judgment, image, all five interpretation categories, and all six changing line texts. Use this for hexagram reference pages, educational content, or lookup after a casting.

You can also look up a hexagram by its binary line pattern:

curl -X GET "https://roxyapi.com/api/v2/iching/hexagrams/lookup?lines=111111" \
  -H "X-API-Key: YOUR_API_KEY"

This finds the hexagram matching the six-digit binary pattern (0 for yin, 1 for yang, bottom to top). Use this when you build custom divination interfaces where users input their own line configurations.

Working Code: Daily Hexagram and Daily Cast

The daily endpoints use date-based seeding so every user with the same seed gets the same hexagram on the same day. Perfect for "Hexagram of the Day" features.

Daily hexagram (simple reading without changing lines):

curl -X POST "https://roxyapi.com/api/v2/iching/daily" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": "user123"}'

Response includes the date, computed seed, full hexagram with interpretations, and a dailyMessage summary string.

Daily cast (full three-coin method with changing lines):

curl -X POST "https://roxyapi.com/api/v2/iching/daily/cast" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": "user123", "date": "2026-04-05"}'

This returns the same structure as the general /cast endpoint but seeded by date. The date field is optional and defaults to today (UTC). Pass a specific date to pre-generate future readings or retrieve past daily castings.

Working Code: Explore Trigrams

Trigrams are the building blocks of hexagrams. The API provides complete reference data for all 8.

List all trigrams:

curl -X GET "https://roxyapi.com/api/v2/iching/trigrams" \
  -H "X-API-Key: YOUR_API_KEY"

Get a specific trigram by number or English name:

curl -X GET "https://roxyapi.com/api/v2/iching/trigrams/Heaven" \
  -H "X-API-Key: YOUR_API_KEY"

Each trigram includes the Chinese name, pinyin, binary pattern, Five Element (Wu Xing) correspondence, core attribute, family member archetype, compass direction, body part, animal symbol, season, energetic quality, and a full meaning description. This data powers trigram reference pages, Bagua diagrams, and educational features explaining how upper and lower trigrams combine to form hexagram meanings.

Use Cases: What You Can Build

The I-Ching API unlocks product categories that no other data source supports.

Divination apps. Users ask a question, cast a reading, and receive the primary hexagram with changing line analysis and the resulting hexagram. Display the six line values with visual indicators for changing lines (old yin and old yang). The seeded casting means users can bookmark or share their reading URL.

Daily wisdom features. Add a "Hexagram of the Day" to any wellness, meditation, or lifestyle app. The daily endpoint guarantees consistency: all users with the same seed see the same hexagram on the same day. The dailyMessage field provides a ready-to-display summary string.

Oracle chatbots and AI agents. Connect the I-Ching API to an AI agent via MCP (Model Context Protocol). The agent discovers all 9 I-Ching tools automatically, casts readings on behalf of users, and interprets the results conversationally. One line of MCP configuration gives Claude, ChatGPT, or any MCP-compatible agent full oracle capabilities.

Decision-making tools. The I-Ching is fundamentally a decision-making framework. Each hexagram includes explicit decision and advice interpretation fields. Build journaling apps where users track situations, cast hexagrams, and review how the guidance relates to outcomes over time.

Spiritual wellness platforms. Combine I-Ching readings with astrology, tarot, numerology, dream interpretation, crystals, and angel numbers under one API key. Roxy covers 9 domains with 122+ endpoints, so your platform can offer multi-system guidance without managing multiple integrations.

MCP Integration for AI Oracle Chatbots

The I-Ching MCP server exposes every endpoint as a tool that AI agents can discover and call. Add this configuration to Claude Desktop, Cursor, or any MCP-compatible client:

{
  "mcpServers": {
    "roxy-iching": {
      "url": "https://roxyapi.com/mcp/iching-api",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Once connected, the AI agent sees tools like castReading, getDailyHexagram, getHexagram, listTrigrams, and more. It can cast readings, look up hexagrams, and weave the results into natural conversation. Users ask "Should I take this job?" and the agent casts a reading, interprets the hexagram, explains the changing lines, and delivers personalized guidance. No custom code required beyond the MCP config.

Frequently Asked Questions

Q: Is there an API for I-Ching readings? A: Yes. The Roxy I-Ching API provides 9 endpoints covering all 64 hexagrams, 384 changing lines, 8 trigrams, three-coin casting with seeded reproducibility, and daily readings. It is the only production I-Ching API with structured JSON responses, multi-language support, and MCP integration for AI agents. See the API reference for the full endpoint list.

Q: How do changing lines work in digital I-Ching implementations? A: Each of the six lines in a hexagram is assigned a value from 6 to 9 using the three-coin method. Values 6 (old yin) and 9 (old yang) are changing lines. Old yin (broken) transforms into yang (solid) and old yang (solid) transforms into yin (broken). The changed lines produce a second "resulting" hexagram showing how the situation will evolve. The API returns both the line values array and the resulting hexagram automatically.

Q: Can I build an I-Ching app without understanding Chinese philosophy? A: Yes. The API returns complete interpretations in plain language for every hexagram, covering general meaning, love, career, decision-making, and practical advice. You do not need domain expertise to display these readings in your app. The structured JSON maps directly to UI components.

Q: What is the difference between the daily hexagram and daily cast endpoints? A: The daily hexagram (POST /daily) returns a single hexagram with interpretations and a daily message. The daily cast (POST /daily/cast) simulates the full three-coin method with line values, changing line positions, and the resulting hexagram if lines change. Use the daily hexagram for simple "wisdom of the day" features and the daily cast for apps that need the complete divination experience.

Q: Does the I-Ching API support multiple languages? A: Yes. All I-Ching endpoints support a lang query parameter with options including English, German, Spanish, Hindi, and Turkish. Hexagram names, interpretations, changing line texts, and trigram descriptions are all localized.

Start Building

The I-Ching has guided decision-makers for 3,000 years. Now you can bring that same wisdom into any app, chatbot, or AI agent with structured API calls. Nine endpoints cover every aspect of the Book of Changes: casting, hexagram reference, trigram data, daily readings, and binary pattern lookup. Explore the full I-Ching API documentation or check pricing to get started.