Exclusive

I-Ching Oracle API

Bring 3,000 years of I-Ching wisdom to your app. In days.

Daily HexagramCast ReadingHexagram …and so much more

<50mslatency
99.95%+uptime

Start building in seconds.

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

Terminal
npm install @roxyapi/sdk
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 go from zero to production in 30 minutes.

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

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

GET /api/v2/iching/cast?seed=user123-question1
{
  "seed": "user123-question1",
  "hexagram": {
    "number": 9,
    "symbol": "䷈",
    "chinese": "小畜",
    "english": "The Taming Power of the Small",
    "pinyin": "Xiǎo Xù",
    "binary": "111011",
    "upperTrigram": "Wind",
    "lowerTrigram": "Heaven",
    "judgment": "Strong momentum is checked by something small, so the restraint is real and temporary and it cannot be broken by force. Dense clouds have gathered and no rain has fallen, so keep working and let the pressure build.",
    "image": "Wind moves across the face of heaven, shaping what it has no power to stop. With only small means at hand, work on the surface of things: refine the form, the manner, and the detail while the substance waits.",
    "interpretation": {
      "general": "Small, gentle efforts are needed now rather than grand gestures. Restrain your ambitions temporarily and focus on modest, steady progress. Like wind gathering clouds before rain, patient cultivation of conditions will eventually lead to the breakthrough you seek.",
      "love": "Gentle influence works better than force in relationships. Small, consistent gestures of care build lasting bonds. This is not the time for dramatic actions but for patient nurturing.",
      "career": "Major moves are premature: focus on small improvements and preparation. Refine your approach and gather strength for later. Gentle persistence wins where force would fail.",
      "decision": "Restraint is necessary. You may achieve small successes, but larger goals require more time and preparation. Work on what is within your immediate power.",
      "advice": "Like clouds gathering before rain, conditions are forming but not yet ready to manifest. Attend to details and cultivate your resources patiently."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "You are turned back, so return to your own road, and no fault attaches to the turning.",
        "meaning": "The first place is the beginning, and this yang line meets the check early and cheaply. Going back to what is genuinely yours is not a defeat here, it is a course correction with no price attached. Take the hint and resume your own way."
      },
      {
        "position": 2,
        "text": "You are drawn back along with the others, and there is good fortune in it.",
        "meaning": "The second place is inner and central, so this yang line does not have to make the retreat alone. Pulling back in company preserves both the relationship and the strength. Go back with the people who are going back and stop treating it as a personal loss."
      }
    ]
  },
  "lines": [
    7,
    7
  ],
  "changingLinePositions": [
    6
  ],
  "resultingHexagram": {
    "number": 5,
    "symbol": "䷄",
    "chinese": "需",
    "english": "Waiting (Nourishment)",
    "pinyin": "Xū",
    "binary": "111010",
    "upperTrigram": "Water",
    "lowerTrigram": "Heaven",
    "judgment": "Strength stands in front of a real danger, and the correct move is to wait with confidence rather than to charge. Waiting here is timing and not passivity, and when the opening comes the crossing succeeds.",
    "image": "Clouds climb into the sky and have not yet let go of their rain. Wait the way they wait: eat well, rest, keep your good humour, and stay ready without straining.",
    "interpretation": {
      "general": "The conditions for action have not yet ripened. Rather than force your way forward, wait with inner confidence and calm. Nourish yourself during this pause. The moment will come when the time is right, and you will be prepared to move decisively.",
      "love": "Be patient in matters of the heart. The relationship you desire may not be ready yet. Nourish yourself during this time of waiting, and the right connection will recognize your light.",
      "career": "Success requires patience: do not force timing. Use this period to prepare, develop skills, and position yourself. When the opportunity arrives, you will be ready.",
      "decision": "The time to act has not yet come. Wait with confidence, not anxiety. Maintain your inner strength and the situation will clarify when the moment is right.",
      "advice": "Wait with sincerity and maintain your well-being. Do not consume yourself with impatience. Enjoy the present moment while keeping faith that the future will unfold properly."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "Waiting far out on the open border, well back from the water.",
        "meaning": "The first place is the beginning, and this yang line stands at the greatest distance from the danger with time still in hand. Nothing needs doing yet, and doing something anyway is the only error available. Keep to the ordinary routine and stay steady."
      },
      {
        "position": 2,
        "text": "Waiting on the sand, near enough to the water that people begin to talk.",
        "meaning": "The second place is inner and central, and this yang line has moved closer to the difficulty and now draws criticism for its stillness. The talk is noise and it is not evidence of anything. Absorb the gossip without answering it and keep waiting, because the end is good."
      }
    ]
  }
}

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

Drop-in UI components & widgets

Render I-Ching 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 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 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

Works with your stack

Claude CodeCursorAntigravityChatGPTWindsurfVS Code CopilotOpenAI AgentsGeminiLangChainCrewAIVercel AI SDK

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 5,960 automated tests per deploy, 828 of them gold-standard tests locked to named external references such as NASA JPL Horizons, with a public MIT benchmark repo anyone can clone and re-run. See how we test.

Multi-language API responses

EnglishDeutschEspanolFrancaisHindiPortuguesRusskiyTurkce

Key Features

Everything you need from our I-Ching API, built for production:

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 seeded reproducibility for personalized daily oracle readings

Daily hexagram and daily cast endpoints with date-based seeding for consistent daily wisdom features, oracle of the day, and contemplation prompts

All Endpoints

Click any endpoint to view detailed documentation, parameters, and response examples.

Get daily I-Ching hexagramReceive 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 I-Ching reading with changing linesCast 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 hexagramsList all 64 hexagramsBrowse 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
Get a random hexagramGet a random hexagramReceive 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 patternLookup hexagram by line patternFind 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 numberGet hexagram by numberRetrieve 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 readingGenerate 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 trigramsRetrieve 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 nameRetrieve 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.

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 I-Ching API

Real-world applications and use cases for integrating I-Ching API into your projects:

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

What developers are saying

DM

Dhani M.

Indie App Developer

Shipped an astrology app over a long weekend. Birth charts, nakshatras, KP cusps, significators. I verified the Lahiri ayanamsha values independently and they line up with my reference. One API key for all of it.

Email feedback
TH

Tom H.

Senior Developer

The OpenAPI spec is the most complete I have seen in this space. Generated a type-safe TypeScript client from it in seconds. Every field has descriptions and examples. Production-grade documentation.

Email feedback
CW

Chris W.

Backend Engineer

Response times consistently under 50ms for numerology and tarot endpoints. The API returns structured JSON with every field documented. Integrated it into our platform in an afternoon.

Email feedback

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.

Getting started with I-Ching API.

From zero to production in 3 steps. No signup required for testing.

3 Steps to Ship

1Install the SDKnpm i @roxyapi/sdk
2Get your API keyView Plans
3Make your first callView Docs

Agent-Ready Infrastructure

MCP

Remote MCP, llms.txt, and AGENTS.md. The full agent-readiness stack for 12 spiritual domains under one key.

  • Remote MCP server — every endpoint auto-discovered as a tool by Claude, ChatGPT, Cursor over Streamable HTTP. No Docker.
  • Token-optimized responses — opt-in compact mode returns the same data with each field name sent once, cutting the tokens your agent reads per call by roughly 40 to 52 percent. Lossless, and one call still counts as one request.
  • llms.txt — AI-native discovery surface for ChatGPT, Perplexity, and Gemini citation
  • AGENTS.md — 2026 execution playbook for Cursor, Codex, Windsurf, Aider, Claude Code, Gemini CLI. Bundled in the SDK.

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

Your AI agentyour model, your voice
Remote MCPauto-discovered, no local setupToken-optimized
Roxy Ephemeris5,960 tests, 828 vs NASA JPL
Verified result12 domains, one flat rate

Your agent grounds every answer in verified calculations and replies in your own voice, so it never hallucinates a chart, date, or reading. No local setup, no AGPL, no hosted-AI markup.

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

I-Ching API FAQ

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 the same question always returns the same reading, which is ideal for shareable or saved readings. One RoxyAPI key covers I Ching and eleven other domains, 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 seeded by date 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 twelve domains, with no per-domain or per-call fees. Activation is instant, so you can be casting hexagrams within minutes of signing up. AI agents connect to our Remote MCP server in seconds, and an AGENTS.md file plus llms.txt mean coding assistants can wire up the I Ching API for you.

Start using I-Ching API today.

Bring 3,000 years of I-Ching wisdom to your app. In days.

All 12 domains included with every plan. Every endpoint, MCP server, SDK, and starters.

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

View Pricing & Get API Key