Skip to content
RoxyAPI
Get API Key

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,957 automated tests per deploy, 3,683 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. No code, agents or code.

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.

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.

Developers

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

No-code widgets and drop-in UI components.

This is what your visitors see. Paste one snippet into Wix, Squarespace, or WordPress and the I-Ching Oracle API reading appears on your site, with no code and no backend. Developers install the same components from npm for Next.js, React, Vue, Svelte, Angular, or plain HTML. MIT licensed and included in every plan.

MIT licensedFramework agnosticThemeable via CSS variablesnpm or CDN
Show all I-Ching Oracle UI componentsShow fewer 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...

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 domain = roxy.iching
SDK docs

Generating your own client? Get the I-Ching OpenAPI schema.

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": 11,
    "symbol": "䷊",
    "chinese": "泰",
    "english": "Peace",
    "pinyin": "Tài",
    "binary": "111000",
    "upperTrigram": "Earth",
    "lowerTrigram": "Heaven",
    "judgment": "The strong is inside and rising, the yielding is outside and coming down, so the two meet and everything moves. This is a fertile season, and the work is to organize it rather than to sit inside it.",
    "image": "Heaven sits beneath the earth, so the two rise and sink into each other and mingle. Divide the season into its parts and regulate them, so that people get the benefit of a good time instead of merely living through it.",
    "interpretation": {
      "general": "Heaven and earth are in harmony. This is a period of peace, prosperity, and natural flow where great things can be accomplished with relative ease. The strong and the yielding work together. Make the most of this fortunate time, as all seasons eventually change.",
      "love": "A harmonious time for relationships. Heaven and Earth are in accord, allowing deep connection. Nurture this peaceful period through mutual appreciation and shared growth.",
      "career": "Prosperity and harmony are present. Collaboration flourishes and obstacles clear. Use this favorable time to advance your goals while maintaining the balance.",
      "decision": "Conditions are favorable for positive outcomes. Move forward with your plans while maintaining the harmony that makes success possible. Share your good fortune.",
      "advice": "Peace comes when the great descends to meet the small and vice versa. Practice reciprocity and humility even in prosperity. Good times do not last forever: use them wisely."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "Pull up one stalk of grass and the tangled roots bring the others with it, so go forward.",
        "meaning": "The first place is the beginning, and this yang line does not move alone, because whatever is connected to it comes along. Advancement now carries a whole network with it. Move, and bring your people with you instead of climbing over them."
      },
      {
        "position": 2,
        "text": "Bear with the uncultivated, ford the river without waiting for a boat, do not forget the distant, and keep no faction.",
        "meaning": "The second place is inner and central, and this yang line has the breadth that a good season demands. Prosperity narrows people, and the correction is deliberate generosity in four directions at once. Include the rough, act when action is required, remember whoever is out of sight, and refuse the clique."
      },
      {
        "position": 3,
        "text": "No plain runs on without a slope and nothing departs without returning, so stay firm and eat your bread in peace.",
        "meaning": "The third place is the exposed threshold, and this yang line is the last of the strong lines, standing where the season is about to turn. Knowing the turn is coming is not pessimism, it is the only way to enjoy the present without being ambushed by it. Stay correct, refuse to grieve in advance, and take the good that is actually here."
      },
      {
        "position": 4,
        "text": "Fluttering down, not boasting of what you hold, going to your neighbours in good faith.",
        "meaning": "The fourth place is close to power, and this yin line comes down to meet the strength below rather than looking down on it. Rank held lightly is what keeps the exchange alive. Approach people directly and without display, and they will come without needing to be warned."
      },
      {
        "position": 5,
        "text": "The ruler gives his own sister in marriage, and the blessing is great.",
        "meaning": "This is the ruling line, and a yin line in the place of authority binds itself to the strength below by alliance instead of command. Power that condescends on purpose earns a loyalty that force cannot buy. Make the union, give up some precedence, and take the good fortune that comes of it."
      },
      {
        "position": 6,
        "text": "The wall crumbles back into the moat it was dug from; do not call out the army, and give your orders only at home.",
        "meaning": "The sixth place is past the peak, and this yin line stands where the good season collapses back into the ground it came from. Force will not hold the wall up, and using it now spends the little that is left. Draw in, govern what is genuinely yours, and accept the humiliation of a smaller field."
      }
    ]
  },
  "lines": [
    7,
    7,
    7,
    6,
    6,
    8
  ],
  "changingLinePositions": [
    4,
    5
  ],
  "resultingHexagram": {
    "number": 43,
    "symbol": "䷪",
    "chinese": "夬",
    "english": "Break-through (Resoluteness)",
    "pinyin": "Guài",
    "binary": "111110",
    "upperTrigram": "Lake",
    "lowerTrigram": "Heaven",
    "judgment": "One corruption remains at the top and it has to be named openly, in public, where everyone can see it. Speak the truth, understand the danger in speaking it, and do not reach for weapons.",
    "image": "The lake has risen to the top of heaven, water piled where it cannot possibly stay, and the burst is coming. Let what you have accumulated flow down to the people below you, and never settle into your own virtue as though it were an achievement.",
    "interpretation": {
      "general": "A decisive breakthrough is needed to remove a lingering negative influence. The situation calls for resolute action, but it must come through proper channels and righteous means. Make your position known openly and be prepared for confrontation, but do not resort to the methods of what you oppose.",
      "love": "Decisiveness is needed in matters of the heart. Bring what has been hidden into the open. Resolution comes through honest confrontation of the truth.",
      "career": "The time for decisive action has arrived. Expose and address what has been problematic. Act with determination but avoid using the same methods as your opponents.",
      "decision": "Make your position known firmly but without aggression. The breakthrough is at hand. Be resolute but generous in victory.",
      "advice": "Resoluteness requires making your case at the court, announcing even to your own allies the danger. Arm yourself with virtue, not weapons. Walk your talk."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "Strength shows in the advancing toes, and the querent goes out without the power to finish, which is a fault.",
        "meaning": "A strong line at the very beginning, in a situation whose entire difficulty sits at the top. The querent has the resolve and none of the preparation. Going now is not courage, it is a mistake with your name written on it."
      },
      {
        "position": 2,
        "text": "A cry of alarm goes up and armed men are moving in the night, and the querent has no need to be afraid.",
        "meaning": "Strong and central, this line is ready, and the readiness is exactly why the ambush fails. The danger is genuine and it is also survivable. Keep the alertness and drop the fear, because fear is what makes people move too early."
      },
      {
        "position": 3,
        "text": "The resolve shows plainly in the face, which is bad; walking on alone the querent is caught in the rain, is spattered, and is resented for it, and in the end there is no blame.",
        "meaning": "The strong line at the exposed threshold is the only one with a direct tie to the corruption above, and it cannot cut that tie cleanly. The querent will be accused of contamination by their own side. Endure the suspicion, since that very connection is what makes the break-through possible and the record clears afterward."
      },
      {
        "position": 4,
        "text": "The skin is gone from the thighs and walking is painful; being led quietly like a sheep would end the trouble, but the querent hears this and will not believe it.",
        "meaning": "A strong line in a yielding place, close to power and unable to sit still. The restlessness is doing the damage, and the cure is to follow rather than to lead. The line says outright that the advice will be refused, which is the real warning: notice that you are refusing it."
      },
      {
        "position": 5,
        "text": "The deep-rooted weed has to be pulled out with complete resolve, and the middle way is kept while doing it.",
        "meaning": "The ruling line is strong and sits directly beneath the single corrupt line at the top. The thing to be removed is close, entrenched, and probably familiar. Take it out entirely and without cruelty, and keep the manner of the removal as clean as the reason for it."
      },
      {
        "position": 6,
        "text": "There is no one left to call to, and the end is bad.",
        "meaning": "This is the one yielding line, past the peak, isolated above five strong ones. It is the corruption itself at the moment it discovers it has no allies. For the querent it is a warning about any part of the situation that is being sustained by nothing except position."
      }
    ]
  }
}

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

Free templates for I-Ching.

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

Show all 4 templatesShow fewer templates

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

Try every endpoint live, free, in the playground.

Real calls against the production API, no account needed. Every endpoint sits in the public OpenAPI spec and is callable as an MCP tool; open one for its parameters and response examples.

Daily hexagram - Daily I-Ching oracle API
Daily hexagram - Daily I-Ching oracle API

Receive 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 API
Cast daily reading with changing lines - I-Ching divination API

Cast 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 API
List all 64 hexagrams - I-Ching hexagram catalog API

Browse 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 API
Random hexagram - I-Ching hexagram picker API

Receive 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 API
Lookup hexagram by line pattern - I-Ching binary lookup API

Find 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 API
Get hexagram by number - I-Ching hexagram detail API

Retrieve 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 API
Cast an I-Ching reading - Hexagram divination API

Generate 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 API
List all 8 trigrams - Bagua trigram catalog API

Retrieve 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 API
Get trigram by number or name - Bagua trigram detail API

Retrieve 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.

What customers are building.

LF
Louise Falkenberg

Course creator, Denmark

I think you have done an amazing job, it must have taken a long time. Clients are happy, and so am I.

Natal chart, transit, horoscope, tarot, dream and crystal readings inside her online courses

MM
Mishaal Murawala

Founder, United States

I use RoxyAPI as the data layer for my astrology assistant. It has been reliable.

An astrology assistant on Vedic and KP, dashas, divisional charts, panchang, Western astrology, numerology and tarot

MF
Mário Feijoca

Founder, Portugal

I really appreciate the quick and helpful support from the RoxyAPI team.

A self-knowledge platform that combines Astrology, Human Design, Numerology, BaZi and other traditions into one personal reading

Every customer story comes from an account we confirmed and is published with the approval of that customer.

Read customer stories

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 agent

your model, your voice

Remote MCP

auto-discovered, no local setup

Token-optimized

Roxy Ephemeris

13,957 tests, 3683 gold standard

Verified result

18+ 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

Included in the same plan as I-Ching Oracle

17 more insight domains

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#, Go, and Rust, 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