I-Ching API for Developers: Hexagrams, Changing Lines, and the Book of Changes

About the author: Hiroshi Kagawa is an I-Ching Scholar and Dream Analyst with 25 years of experience researching the I-Ching as a decision-making and divination framework. He holds a Ph.D. in East Asian Philosophy from Kyoto University, has translated two classical I-Ching commentaries into modern Japanese, and teaches hexagram interpretation. His work on dream symbolism in Buddhist and Taoist traditions is widely cited in East Asian metaphysics literature.

The I-Ching (Book of Changes) is one of the oldest texts in human history, a 3,000-year-old Chinese oracle system still used daily by millions of people for personal guidance and decision-making. Yet until now, no production-quality API has existed for developers who want to bring this wisdom into modern software. Search for "I-Ching API" and you will find a dead npm library from 2018, a few Wikipedia pages, and nothing usable. That gap is now closed. Roxy provides a structured, developer-ready I-Ching API with 64 hexagrams, 384 changing lines, 8 trigrams, daily readings, and authentic three-coin casting. This article explains the system, the data model, and how to integrate it.

What is the I-Ching and why does it matter for developers?

The I-Ching, also called the Book of Changes (Yi Jing in Mandarin), is a divination and philosophical text originating in China around 1000 BCE. It is built on a system of 64 hexagrams, each composed of six stacked lines that are either solid (yang) or broken (yin). The hexagrams represent archetypal life situations, from "The Creative" (pure initiative) to "The Receptive" (patient devotion) to "Conflict" and "Waiting." Each hexagram carries a Judgment text, an Image text, and six changing line interpretations that add layers of nuance to a reading.

For developers, the I-Ching offers structured, symbolic data that maps perfectly to decision-making interfaces, daily oracle features, AI chatbot tools, and educational apps focused on Chinese philosophy. The system is deterministic yet rich: 64 hexagrams times 6 lines equals 384 individual interpretations, plus 8 trigrams with their own element, direction, and attribute correspondences. All of this data is now available as structured JSON through a REST API.

Ready to build this? Roxy I-Ching API gives you 64 hexagrams, 384 changing lines, and 8 trigrams with one API key. See pricing.

How the 64 hexagrams encode 3,000 years of wisdom

Each of the 64 hexagrams is built from two trigrams stacked together: a lower trigram (lines 1 through 3) and an upper trigram (lines 4 through 6). The 8 trigrams represent fundamental forces of nature: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, and Lake. Every possible pairing of these 8 trigrams produces one of 64 hexagrams, each with a unique meaning.

A hexagram in the Roxy API returns its King Wen sequence number (the traditional ordering used for over 3,000 years), the original Chinese name, English translation, pinyin romanization, Unicode symbol, binary line pattern, and both trigram names. Beyond the classical texts, every hexagram includes modern interpretations across five life areas: general guidance, love, career, decision-making, and practical advice. These interpretations make the data immediately usable in consumer apps without requiring users to decode ancient Chinese metaphor on their own.

What are changing lines and how do they transform readings?

Changing lines are what make the I-Ching a dynamic divination system rather than a static reference. When you cast a reading using the three-coin method, each line receives a value between 6 and 9. Values of 7 (young yang) and 8 (young yin) are stable. Values of 6 (old yin) and 9 (old yang) are "changing" lines, meaning they transform into their opposite. Old yin becomes yang. Old yang becomes yin.

When a hexagram contains changing lines, it transforms into a second hexagram called the "resulting hexagram." This creates a narrative arc: the primary hexagram describes the current situation, the changing lines highlight specific areas of flux, and the resulting hexagram shows where the situation is heading. With 6 lines per hexagram and 64 hexagrams, the system contains 384 individual changing line texts. Each one offers specific guidance for that line position in that hexagram. The Roxy I-Ching API returns all of this in a single cast request.

How does the three-coin casting method work in an API?

The traditional three-coin method involves tossing three coins six times to build a hexagram from the bottom up. Each toss produces heads or tails on three coins. Heads counts as 3, tails as 2. The sum of three coins yields a value between 6 and 9. A sum of 6 (all tails) produces old yin, a changing broken line. A sum of 7 (two tails, one heads) produces young yang, a stable solid line. A sum of 8 (two heads, one tails) produces young yin, a stable broken line. A sum of 9 (all heads) produces old yang, a changing solid line.

The Roxy API implements this digitally with cryptographic randomness. A single GET /cast request simulates six three-coin tosses and returns the primary hexagram, the line values array, the positions of any changing lines, and the resulting hexagram if transformation occurs. You can also pass an optional seed parameter for reproducible results, making the endpoint suitable for apps where the same user and question should always produce the same reading.

The 8 trigrams: building blocks of every hexagram

Trigrams are the atomic units of the I-Ching system. Each trigram consists of three lines (yang or yin) and represents a primal force. The 8 trigrams and their core attributes are:

The Roxy trigram endpoints return all of these correspondences plus family member archetypes, body part associations, animal symbols, seasonal timing, and detailed meaning texts. This data is essential for feng shui applications, Bagua analysis tools, and any interface that needs to explain why a hexagram means what it means.

How to build an I-Ching app with the Roxy API

The I-Ching API is mounted at /api/v2/iching/ and requires an API key sent in the X-API-Key header. Here are working examples for the most common use cases.

Cast a full I-Ching reading with changing lines:

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

{
  "hexagram": {
    "number": 1,
    "symbol": "䷀",
    "chinese": "乾",
    "english": "The Creative",
    "pinyin": "Ch'ien",
    "binary": "111111",
    "upperTrigram": "Heaven",
    "lowerTrigram": "Heaven",
    "judgment": "The Creative works sublime success, Furthering through perseverance.",
    "image": "The movement of heaven is full of power. Thus the superior man makes himself strong and untiring.",
    "interpretation": {
      "general": "A time of great creative power and initiative...",
      "love": "A time of strong creative energy and passionate connection...",
      "career": "Exceptional opportunities for advancement and recognition await...",
      "decision": "The time is right for bold action...",
      "advice": "Be like the heavens, consistent, powerful, and untiring..."
    },
    "changingLines": [
      { "position": 1, "text": "Hidden dragon. Do not act." },
      { "position": 2, "text": "Dragon appearing in the field..." },
      { "position": 3, "text": "All day long the superior man is creatively active..." },
      { "position": 4, "text": "Wavering flight over the depths. No blame." },
      { "position": 5, "text": "Flying dragon in the heavens..." },
      { "position": 6, "text": "Arrogant dragon will have cause to repent." }
    ]
  },
  "lines": [7, 8, 9, 7, 6, 8],
  "changingLinePositions": [3, 5],
  "resultingHexagram": {
    "number": 44,
    "symbol": "䷫",
    "english": "Coming to Meet",
    "interpretation": { "..." : "..." }
  }
}

Get the daily hexagram for your app:

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

This returns the same hexagram for the same seed on the same day, making it perfect for "Hexagram of the Day" features where each user gets a consistent daily reading.

Look up a specific hexagram by number:

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

Look up a hexagram by its binary line pattern:

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

List all 8 trigrams:

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

All endpoints support multi-language responses via the ?lang= query parameter with 8 supported languages.

Explore the full endpoint list and test live in the I-Ching API reference.

Use cases: what developers are building with I-Ching data

The I-Ching API unlocks a category of applications that previously required custom data sets and deep domain expertise. Here are the most common use cases.

Divination and oracle apps. The /cast endpoint delivers a complete three-coin reading with a single API call. Pair it with a visual hexagram renderer and you have a full I-Ching oracle. The seed parameter lets you tie readings to user accounts or specific questions for reproducibility.

Daily wisdom and oracle features. The /daily endpoint provides a consistent hexagram per user per day, perfect for push notifications, email digests, or in-app "guidance of the day" widgets. The /daily/cast variant adds changing lines for a richer daily experience.

AI I-Ching chatbots. Feed the structured interpretation fields (general, love, career, decision, advice) into an LLM prompt and you get a conversational I-Ching advisor. The hexagram judgment and image texts provide grounding context that prevents hallucination.

Chinese philosophy education. The trigram endpoint returns element, direction, family member, body part, animal, and seasonal correspondences for each of the 8 trigrams. Build interactive Bagua diagrams, study tools, or curriculum supplements.

Decision-making tools. The I-Ching has been used as a decision framework for millennia. The five interpretation categories (general, love, career, decision, advice) map directly to structured UI for apps that help users reflect before making choices.

Frequently Asked Questions

Q: Is there an API for I-Ching readings? A: Yes. Roxy provides the only production I-Ching API with all 64 hexagrams, 384 changing lines, 8 trigrams, three-coin casting, daily readings, and multi-language support. All data is returned as structured JSON with interpretations for love, career, decisions, and general guidance.

Q: How do changing lines work in digital I-Ching implementations? A: The API simulates the traditional three-coin method. Each of the six lines receives a value from 6 to 9. Lines with values 6 (old yin) or 9 (old yang) are changing lines that transform into their opposite, producing a second "resulting hexagram." The API returns both hexagrams, the line values, and the changing line positions in one response.

Q: Can I build an I-Ching app without understanding Chinese philosophy? A: Yes. The API returns modern English interpretations for every hexagram across five categories: general, love, career, decision-making, and advice. You do not need to study the Book of Changes to present meaningful readings to your users. The structured data handles the interpretation layer for you.

Q: What is the difference between a hexagram lookup and a cast reading? A: A hexagram lookup (GET /hexagrams/{number}) retrieves a specific hexagram by its King Wen sequence number, returning its full data as a reference. A cast reading (GET /cast) simulates the three-coin method, randomly generating line values that determine both the primary hexagram and any resulting hexagram from changing lines. Lookups are for reference. Castings are for divination.

Q: How does the three-coin method work in an API? A: The API simulates tossing three coins six times. Each toss produces a line value: 6 (old yin, changing), 7 (young yang, stable), 8 (young yin, stable), or 9 (old yang, changing). Six tosses build a hexagram from bottom to top. If any lines are changing, the API computes the resulting hexagram automatically. Pass a seed parameter for reproducible castings tied to a user or question.

Start building with the I-Ching API

The I-Ching has guided decision-making for 3,000 years. Now it is available as structured JSON with a single API call. Whether you are building a divination app, a daily oracle feature, an AI chatbot grounded in Chinese philosophy, or an educational tool for hexagram study, the Roxy I-Ching API gives you everything you need: 64 hexagrams, 384 changing lines, 8 trigrams, three-coin casting, seeded daily readings, and multi-language support. See pricing and get your API key.