Skip to content

I-Ching Oracle API

An I Ching reading that interprets every changing line, not just the hexagram it lands on.

Daily HexagramI Ching ReadingHexagramTrigram

What the I-Ching Oracle API covers.

Castings

  • Three-coin casting with old and young lines
  • Every changing line read by position and polarity
  • Resulting hexagram the reading transforms into
  • Hexagram of the day and a daily cast

Hexagrams

  • King Wen sequence with Chinese name and pinyin
  • Judgment and Image for every hexagram
  • Readings for love, career and decisions
  • Lookup by yin and yang line pattern

Trigrams

  • Bagua trigrams as upper and lower pairs
  • Element, direction, season and family member
  • Body part, animal and core attribute

I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career, and decision-making. Cast readings with the authentic three-coin method, get a daily hexagram, and explore the Book of Changes programmatically. Built for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.

Every I-Ching calculation is covered by 13,405 automated tests per deploy, 3,620 of them gold-standard tests locked to the named references on our methodology page. See how we test.

Interpretations in English, Deutsch, Español, Français, हिन्दी, Português, Русский, Türkçe, one query parameter away.

Start your way. Code, agents or no code.

Developers

Typed SDKs for TypeScript, Python, PHP, C#, and Go, generated from the live spec, each with an AGENTS.md so your coding assistant calls the I-Ching Oracle API correctly.

AI agents

A Remote MCP server exposes every endpoint as a tool for Claude, ChatGPT, Cursor and any MCP client, with no local install. Opt-in compact responses cut the tokens your agent reads by roughly 40 to 52 percent, and one call stays one request.

No-code builders

Paste a widget into any site builder, install the WordPress plugin, or start from an MIT template you can white-label. Results render from the I-Ching Oracle API with no backend.

I-Ching Oracle API features, in detail.

The depth behind every line above, written out in full.

  • Complete 64 hexagram database with King Wen sequence, traditional Chinese names, pinyin, Unicode symbols, and binary patterns for authentic I-Ching readings
  • Modern interpretations for each hexagram covering general meaning, love and relationships, career guidance, decision-making wisdom, and actionable advice
  • 384 changing lines (6 lines x 64 hexagrams), each with its oracle statement AND a written meaning that reads the line from its position in the hexagram and its yin or yang, so an agent never has to invent what a moving line is telling you
  • Authentic three-coin casting method with changing lines, resulting hexagram transformation, and castings that reopen unchanged when shared or saved
  • Daily hexagram and daily cast that stay the same for one user all day, for daily wisdom features, oracle of the day, and contemplation prompts

Start building with one key.

Want to try without writing code? Try this domain live in API playground →

Terminal
npm install @roxyapi/sdk
Usage
import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.get(/* ... */)
SDK docs

Want to ship faster? Clone a free template and white-label it as your own app.

Building with Cursor, Claude Code, or Bolt? Use our AI prompts to generate a complete app.

Building on WordPress? Install the RoxyAPI plugin and drop a shortcode, no code required.

GET /api/v2/iching/cast
{
  "hexagram": {
    "number": 19,
    "symbol": "䷒",
    "chinese": "臨",
    "english": "Approach",
    "pinyin": "Lín",
    "binary": "110000",
    "upperTrigram": "Earth",
    "lowerTrigram": "Lake",
    "judgment": "Strength is rising from below and the ground ahead is open, so advance while the season favors it. Nothing expands forever, and the reversal is already scheduled, so use the opening now.",
    "image": "The earth stands above the lake, high ground looking down into the depth it contains. Teach without ever running out of patience, and protect people without setting a limit on who counts.",
    "interpretation": {
      "general": "Favorable conditions are approaching and influence is growing. This is an auspicious time for taking initiative, mentoring others, and expanding your reach. However, remember that every advance eventually turns into retreat. Act now while conditions support you.",
      "love": "A favorable time for approaching someone or deepening a connection. Move toward what you desire with confidence and genuine care. Opportunities are opening.",
      "career": "Success approaches when you take steps to meet it. This is a favorable time for outreach, expansion, and new beginnings. Act while conditions are supportive.",
      "decision": "The time is right to move forward. Approach your goals actively rather than waiting passively. Favorable conditions will not last forever: act now.",
      "advice": "Great success comes through perseverance. Use this favorable period wisely, for conditions will shift. Teach and support others while your influence is strong."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "The approach begins in good company, and correctness makes it fortunate.",
        "meaning": "The first line is strong and at the start of the rise, moving upward alongside its partner. Energy is abundant and completely untested, which is exactly when it goes wrong. Advance, but bind the advance to something correct, because at the beginning nobody is checking you."
      },
      {
        "position": 2,
        "text": "The approach continues in good company, and every direction is open.",
        "meaning": "The second place is inner, central, and supported, and a strong line here has both drive and balance. This is the most favorable moment in the entire rise. Move on it, and do not spend the momentum waiting for a guarantee that will not come."
      },
      {
        "position": 3,
        "text": "Approaching for the pleasure of approaching brings no advantage.",
        "meaning": "Line three is the exposed threshold, and a yielding line there has climbed on borrowed momentum instead of earned strength. Advancing because it feels good is not the same as advancing because it is correct, and this position cannot carry the difference. Worry about it honestly and the error corrects itself."
      },
      {
        "position": 4,
        "text": "The approach is made in the fullest way, and nothing is out of place.",
        "meaning": "The fourth line is yielding, properly placed, close to power, and connected to the strength below. It does not compete with the rise, it lets the rise reach it. Meeting capable people directly, without status games, is what makes this line faultless."
      },
      {
        "position": 5,
        "text": "This is the approach of intelligence, which is what suits a ruler.",
        "meaning": "The fifth place is the seat of authority, and a yielding line here governs by knowing its own limits. Wisdom in this position means putting the strong and capable where they belong and then standing out of their way. The right use of power here is selection, not exertion."
      },
      {
        "position": 6,
        "text": "The approach is generous and honest, and it does no harm.",
        "meaning": "At the top the momentum is spent, and a yielding line has nothing further to gain from advancing. What remains possible is giving: it turns back toward the beginners below and supports them. Past the peak an open hand carries further than another push."
      }
    ]
  },
  "lines": [
    7,
    9,
    8,
    8,
    8,
    8
  ],
  "changingLinePositions": [
    2
  ],
  "resultingHexagram": {
    "number": 24,
    "symbol": "䷗",
    "chinese": "復",
    "english": "Return (The Turning Point)",
    "pinyin": "Fù",
    "binary": "100000",
    "upperTrigram": "Earth",
    "lowerTrigram": "Thunder",
    "judgment": "The turn has already happened at the bottom, where nothing shows yet, and coming and going meet no obstruction, so allies arrive and nothing goes wrong. Let the cycle return on its own schedule, and have somewhere to go when it does.",
    "image": "Thunder is buried inside the earth, the year turning at its coldest point. Close the passes and stay still, because an impulse this new is protected by rest rather than by activity.",
    "interpretation": {
      "general": "After a period of darkness or decline, the first signs of renewal appear. Like the winter solstice when light begins to return, the turning point has arrived. Allow this natural return of energy to unfold at its own pace. Rest, recover, and let growth resume gradually.",
      "love": "A fresh start is possible in love. Return to the authentic feelings that first drew you together. After a period of separation or coldness, warmth can return.",
      "career": "Energy returns after a period of decline. New beginnings are favored. This is a turning point where momentum shifts in a positive direction.",
      "decision": "After a period of withdrawal, the time to act returns. Begin again with fresh energy. Small steps now lead to great progress later.",
      "advice": "After the darkest point, the light returns. Rest during the solstice and let vitality restore itself. The returning energy should not be spent hastily."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "The return is made after only a few steps, before anything needed repenting.",
        "meaning": "The first line is the single strong line and the turning point of the whole hexagram, but it is still hidden at the bottom. You caught the deviation early, which is the only time catching it is free. Go back now, without ceremony and without constructing a story about it."
      },
      {
        "position": 2,
        "text": "The return is made willingly, and it is a fine thing to watch.",
        "meaning": "Line two is inner, central, and yielding, close enough to the returning line below to be carried by it. Turning back is easier beside someone already doing it, so let that pull work on you. There is no loss of standing in following a correction that is right."
      },
      {
        "position": 3,
        "text": "The return is made over and over, which is dangerous but not wrong.",
        "meaning": "Line three is the exposed threshold, and a yielding line there is unstable, so it leaves the path, comes back, and leaves again. This is exhausting and it looks unserious, but the returning is the part that counts. Keep coming back, and stop pretending the wandering was deliberate."
      },
      {
        "position": 4,
        "text": "You walk in the middle of the crowd and turn back alone.",
        "meaning": "The fourth line is surrounded by yielding lines all going the other way, and it alone holds a link to the strong line at the bottom. Nobody around you will validate the turn, and waiting for their approval means never making it. Return alone, and do not explain yourself."
      },
      {
        "position": 5,
        "text": "The return is made honestly, and there is nothing to regret.",
        "meaning": "The fifth place rules, and a yielding line here has no strength to hide behind, only candor. The right use of authority in a reversal is to own the error plainly, with no theatre and no excuse. Done that way it costs nothing and settles everything."
      },
      {
        "position": 6,
        "text": "The moment for returning is missed entirely, and the armies march out to a defeat that lasts ten years.",
        "meaning": "The top line is past the peak of the cycle and still refusing to turn. A yielding line here has no strength to justify the persistence, so persistence becomes disaster and takes everyone else down with it. Refusing to reverse after the season has already reversed is the most expensive mistake in this hexagram."
      }
    ]
  }
}

Structured JSON with documented fields. Not hallucinated text. See all endpoints

Drop-in UI components and no-code widgets.

Render I-Ching Oracle API responses without building charts yourself. Install the npm package and drop these into Next.js, React, Vue, Svelte, Angular, or plain HTML, or embed the very same component on Squarespace, Wix, or WordPress by pasting one snippet, with no backend and no build step. They belong to one library that covers the entire spiritual stack rather than astrology alone, MIT licensed and included in every plan at no extra cost, never a separate product and never an upsell. The I-Ching Oracle API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.

MIT licensedFramework agnosticThemeable via CSS variablesnpm or CDN
Show all I-Ching Oracle UI components
ElementRenders
<roxy-hexagram>Hexagram figure with trigrams, judgment, image, and a reading per line (statement plus meaning); a cast highlights the moving lines and the resulting hexagram
<roxy-reference-card>Symbol, name, description, keyword chips, and an attribute grid for any glossary lookup

Component preview

The real component, running on sample data.

Loading the component...

Free templates for I-Ching.

Clone. Edit. Ship. Free and open source by Team Roxy.

Browse all templates or use AI prompts to generate a custom app.

What you can build with the I-Ching Oracle API.

The products teams ship on the I-Ching Oracle API.

  • Build I-Ching divination apps with authentic coin-toss readings: users ask their question and receive complete hexagram interpretations with changing lines and transformations
  • Add daily oracle features to wellness and meditation apps: daily hexagrams, daily cast readings, and contemplation prompts from 3,000 years of Chinese philosophy
  • Build AI I-Ching chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers oracle endpoints and delivers conversational hexagram readings
  • Create Chinese philosophy education platforms teaching the Book of Changes, Taoist principles, trigram symbolism, and hexagram patterns through interactive exploration
  • Ship comprehensive spiritual guidance platforms combining I-Ching with astrology, tarot, numerology, and dream interpretation under one API key
  • Power decision-making and journaling apps: users record situations, cast hexagrams, track how readings relate to outcomes, and gain clarity through structured ancient wisdom

All 9 endpoints, live in the playground.

Every one is live in the public OpenAPI spec and callable as an MCP tool. Click any endpoint to view detailed documentation, parameters, and response examples.

Daily hexagram - Daily I-Ching oracle APIReceive a daily I-Ching hexagram for guidance and reflection. This endpoint uses seeded randomness to ensure the same seed gets the same hexagram on the same day, perfect for "Hexagram of the Day" features in oracle apps, meditation platforms, and daily wisdom tools. Returns the hexagram with judgment, image, and interpretations for love, career, decisions, and practical advice based on ancient Chinese wisdom from the Book of Changes.Cast daily reading with changing lines - I-Ching divination APICast a complete daily I-Ching reading using the traditional three-coin method with seeded randomness. Unlike the simple daily hexagram, this provides the full casting experience with line values (6-9), changing line positions, and the resulting hexagram if transformation occurs. Same seed + same date = same casting result. Perfect for I-Ching divination apps requiring authentic oracle experience with daily consistency.
List all 64 hexagrams - I-Ching hexagram catalog APIList all 64 hexagrams - I-Ching hexagram catalog APIBrowse all 64 I-Ching hexagrams from the Book of Changes with their Chinese names, English translations, and trigram compositions. The hexagrams are ordered by the traditional King Wen sequence used in I-Ching divination for 3,000 years. Each hexagram represents a unique life situation combining two trigrams (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake) into profound wisdom for decision-making and self-understanding.Try it
Random hexagram - I-Ching hexagram picker APIRandom hexagram - I-Ching hexagram picker APIReceive a random I-Ching hexagram with full interpretation. Perfect for daily oracle features, meditation prompts, or exploring the Book of Changes. Returns complete hexagram data including judgment, image, interpretations for love/career/decisions, and all six changing line meanings.Try it
Lookup hexagram by line pattern - I-Ching binary lookup APILookup hexagram by line pattern - I-Ching binary lookup APIFind an I-Ching hexagram by its binary line pattern. Provide 6 digits (0 or 1) representing broken (yin) and solid (yang) lines from bottom to top. Use this for custom divination interfaces where users input their own line configurations, or to find hexagrams matching specific trigram combinations. Example: "111111" returns Hexagram 1 (The Creative), "000000" returns Hexagram 2 (The Receptive).Try it
Get hexagram by number - I-Ching hexagram detail APIGet hexagram by number - I-Ching hexagram detail APIRetrieve complete I-Ching hexagram details by King Wen sequence number (1-64). Returns the full hexagram with Chinese name, English translation, judgment text, image text, modern interpretations for general situations, love, career, and decision-making, plus all six changing line meanings. Use this to display detailed hexagram information after casting or for educational reference.Try it
Cast an I-Ching reading - Hexagram divination APIGenerate an authentic I-Ching reading using the traditional three-coin casting method. Each of the six lines is determined by virtually tossing three coins, producing values 6-9 where 6 (old yin) and 9 (old yang) are changing lines. Returns the primary hexagram with full interpretation, the line values showing which lines are changing, and if any lines change, the resulting hexagram that the primary transforms into. Optionally provide a seed for reproducible castings. Perfect for divination apps, oracle features, and decision-making tools.List all 8 trigrams - Bagua trigram catalog APIRetrieve all 8 I-Ching trigrams (bagua), the fundamental building blocks of hexagrams. Each trigram consists of three lines and represents a primal force of nature: Heaven (Qian), Earth (Kun), Thunder (Zhen), Wind (Xun), Water (Kan), Fire (Li), Mountain (Gen), and Lake (Dui). Understanding trigrams is essential for interpreting hexagram meanings, as each hexagram combines an upper and lower trigram.Get trigram by number or name - Bagua trigram detail APIRetrieve a specific I-Ching trigram by its number (1-8) or English name (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake). Returns complete trigram information including Chinese name, pinyin, element associations, core attributes, and symbolic meaning. Use this to understand the component trigrams of any hexagram.

Do not take our word for it. Ask the agents.

The receipts are public: the testing methodology, the open MIT benchmark, the transparency report, and the live API playground. Let ChatGPT, Perplexity, or Claude search the web and tell you what they find about RoxyAPI accuracy, MCP, SDKs, and pricing.

Opens a live web search in a new tab.

From your AI agent to a verified I-Ching answer.

Your AI agentyour model, your voice
Remote MCPauto-discovered, no local setupToken-optimized
Roxy Ephemeris13,405 tests, 3620 gold standard
Verified result18 domains, one flat rate

Your agent uses calculated charts and readings in its replies, with your model and your own voice. Planetary positions are verified against NASA JPL Horizons. No local setup, no AGPL, no hosted-AI markup.

Audit it yourself: every I-Ching endpoint runs live in the API playground

I-Ching Oracle API questions, answered.

How do I cast an I-Ching hexagram with an API?

The I Ching API casts a reading with the traditional three-coin method in a single call and returns the primary hexagram, its full interpretation, the six lines read bottom to top, and any changing lines. You can pass an optional seed so a casting can be reproduced exactly, which is ideal for shareable or saved readings. One RoxyAPI key covers I Ching and every other RoxyAPI domain, activation is instant, and the same casting is available to AI agents as a tool on our Remote MCP server with no local setup or Docker.

Does the API return changing lines and the resulting hexagram?

Yes. Every cast reports which lines are moving and, when one or more change, returns the resulting hexagram the reading transforms into, with its own judgment, image, and interpretation. Each of the six lines carries both its oracle statement and a written meaning, so you can explain exactly what a moving line is asking for rather than handing a user a line of archaic verse and leaving them to guess. That is the depth that turns a simple draw into a real I Ching reading, and it is why an LLM reading our payload does not have to make the interpretation up.

Does the API include all 64 hexagrams of the Book of Changes?

Yes. The full 64-hexagram catalog ships in the traditional King Wen sequence, each with its Chinese name, pinyin with tone marks, Unicode symbol, upper and lower trigram, judgment, image, and layered interpretations for general guidance, love, career, and decisions. You can browse the whole catalog or fetch a single hexagram by its number. The readings are our own editorial content, written from the mechanics of the hexagram and checked against the tradition, so you can build a complete reference without sourcing and licensing the text yourself.

Can I look up an I-Ching hexagram by its line pattern or trigrams?

Yes. The I Ching API resolves any six-line yin and yang pattern to its matching hexagram, so interfaces where users enter their own lines work out of the box. You also get all eight trigrams, the bagua building blocks such as Heaven, Earth, Fire, and Water, and every hexagram names its upper and lower trigram. Pair them to explain how two trigrams combine into a single meaning.

How do I add a daily I-Ching hexagram to my app?

The I Ching API offers a daily hexagram and a full daily cast, both stable for the day so a given user sees the same result all day. That is exactly what oracle of the day, mindfulness, and contemplation features need, and it powers AI wisdom chatbots that reflect on one hexagram each morning. Drop it in with our typed SDKs for TypeScript, Python, PHP, C#, and Go, the WordPress plugin, or ready-made UI components.

How much does the I-Ching API cost and how fast can I ship?

Pricing is flat and predictable: one subscription unlocks I Ching plus astrology, tarot, numerology, dreams, and the rest of the catalogue, with no per-domain or per-call fees. Activation is instant, so you can start casting hexagrams as soon as you sign up. AI agents connect to our Remote MCP server with no local setup, and an AGENTS.md file plus llms.txt mean coding assistants can wire up the I Ching API for you.

Start using I-Ching Oracle API today.

An I Ching reading that interprets every changing line, not just the hexagram it lands on.

All 18 domains included with every plan. Every endpoint, MCP server, SDK, and templates.

Plans from $39/mo, starting at $1.80 per domain on annual billing. No credit card required for testing.

View Pricing & Get API Key