Exclusive

I-Ching Oracle API

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

<50mslatency
99.9%uptime
9+endpoints

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": "roxy-demo",
  "hexagram": {
    "number": 25,
    "symbol": "䷘",
    "chinese": "無妄",
    "english": "Innocence (The Unexpected)",
    "pinyin": "Wu Wang",
    "binary": "111001",
    "upperTrigram": "Thunder",
    "lowerTrigram": "Heaven",
    "judgment": "Innocence. Supreme success. Perseverance furthers. If someone is not as he should be, He has misfortune, And it does not further him To undertake something.",
    "image": "Under heaven thunder rolls: All things attain the natural state of innocence. Thus the kings of old, Rich in virtue, and in harmony with the time, Fostered and nourished all beings.",
    "interpretation": {
      "general": "Act with spontaneous sincerity and natural integrity, free from calculation or ulterior motives. When your actions arise from genuine inner truth rather than strategic thinking, the universe supports you. Unexpected events are part of the natural order. Accept them without blame.",
      "love": "Approach love with sincerity and without ulterior motives. Genuine connection comes from innocence of intention. Let go of manipulation and expectation.",
      "career": "Success comes from acting with integrity and without calculation. Trust the natural course of events. Unexpected good fortune comes to those who are sincere.",
      "decision": "Act naturally without overthinking or scheming. Trust that right action leads to right outcomes. Deviating from your true nature brings misfortune.",
      "advice": "Innocence means acting in accord with your true nature and the natural order. Forced action brings unexpected difficulties. Be genuine and accept what comes."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "Innocent behavior brings good fortune."
      },
      {
        "position": 2,
        "text": "If one does not count on the harvest while plowing, Nor on the use of the ground while clearing it, It furthers one to undertake something."
      },
      {
        "position": 3,
        "text": "Undeserved misfortune. The cow that was tethered by someone Is the wanderer's gain, the citizen's loss."
      },
      {
        "position": 4,
        "text": "He who can be persevering Remains without blame."
      },
      {
        "position": 5,
        "text": "Use no medicine in an illness Incurred through no fault of your own. It will pass of itself."
      },
      {
        "position": 6,
        "text": "Innocent action brings misfortune. Nothing furthers."
      }
    ]
  },
  "lines": [
    7,
    9,
    7,
    8,
    8,
    7
  ],
  "changingLinePositions": [
    2
  ],
  "resultingHexagram": {
    "number": 21,
    "symbol": "䷔",
    "chinese": "噬嗑",
    "english": "Biting Through",
    "pinyin": "Shih Ho",
    "binary": "101001",
    "upperTrigram": "Thunder",
    "lowerTrigram": "Fire",
    "judgment": "Biting Through has success. It is favorable to let justice be administered.",
    "image": "Thunder and lightning: The image of Biting Through. Thus the kings of former times made firm the laws Through clearly defined penalties.",
    "interpretation": {
      "general": "An obstacle blocks the path and must be removed decisively. Like biting through something hard to unite what has been separated, this situation calls for firm action and clear judgment. Legal matters, enforcement of standards, or cutting through deception may be required.",
      "love": "Obstacles in the relationship must be confronted directly. Clear away what blocks true connection. Sometimes love requires decisively dealing with problems.",
      "career": "Take decisive action to break through obstacles. Enforce standards and address problems that have been allowed to fester. Justice and clarity are needed.",
      "decision": "The situation requires forceful action to break through resistance. Do not be timid—address the obstacle directly. Decisive measures bring success.",
      "advice": "When something obstructs, bite through it. This is a time for clear action and the enforcement of standards. Obstacles must be removed for harmony to return."
    },
    "changingLines": [
      {
        "position": 1,
        "text": "His feet are fastened in the stocks, So that his toes disappear. No blame."
      },
      {
        "position": 2,
        "text": "Bites through tender meat, So that his nose disappears. No blame."
      },
      {
        "position": 3,
        "text": "Bites on old dried meat And strikes on something poisonous. Slight humiliation. No blame."
      },
      {
        "position": 4,
        "text": "Bites on dried gristly meat. Receives metal arrows. It furthers one to be mindful of difficulties And to be persevering. Good fortune."
      },
      {
        "position": 5,
        "text": "Bites on dried lean meat. Receives yellow gold. Perseveringly aware of danger. No blame."
      },
      {
        "position": 6,
        "text": "His neck is fastened in the wooden cangue, So that his ears disappear. Misfortune."
      }
    ]
  }
}

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

Works with your stack

Claude CodeCursorAntigravityChatGPTWindsurfVS Code CopilotOpenAI AgentsGeminiLangChainCrewAIVercel AI SDK

I-Ching oracle API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Access 3,000 years of Chinese wisdom 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 daily hexagrams, and explore the Book of Changes programmatically. 9+ endpoints optimized for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products.

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 line interpretations (6 lines x 64 hexagrams) explaining how each line transforms your reading and what the transition means for your situation

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

AI-optimized JSON responses with structured hexagram data, trigram analysis, and interpretations, perfect for MCP-powered I-Ching chatbots and LLM integration

Multi-language responses in 8 languages (EN, TR, DE, ES, HI, PT, FR, RU) via ?lang= query parameter

All 9+ 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 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.Get 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.Lookup 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).Get 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.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.

AI astrology chatbot template with MCP integration, horoscope, tarot, numerology, birth chart, and Vedic astrology powered by RoxyAPI

AI Astrology Chatbot

Web App / Open Source30 min

AI chatbot with real readings across all spiritual domains. Not hallucinations.

AstrologyVedicTarotNumerologyCrystalsDreamsI-ChingAngel Numbers
AI spiritual voice assistant template with embeddable voice widget for astrology, tarot, numerology, and Vedic readings powered by RoxyAPI

AI Spiritual Voice Assistant

Web App / Open Source30 min

Talk to the stars. Real readings across every spiritual domain, spoken aloud.

VoiceAstrologyVedicTarotNumerologyHuman Design

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.

Every page here is built so AI search engines can read and cite it, so go straight to the source. 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 — 9+ tools auto-discovered by Claude, ChatGPT, Cursor over Streamable HTTP. No Docker.
  • 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.

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 hexagram also carries the text for all six changing lines, so you can explain exactly what a transition means rather than just naming it. This is the depth that turns a simple draw into a real I Ching reading.

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, Unicode symbol, 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. It is curated content across eight languages, so you can build a complete reference without sourcing and translating 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, and PHP, 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. 9+ endpoints, MCP server, SDK, and starters.

Plans from $39/mo — thats $3.25 per domain. No credit card required for testing.

View Pricing & Get API Key