I Ching Hexagram API
I-Ching binary lookup API
Included with every plan (at no extra cost)
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).
Request
GET /api/v2/iching/hexagrams/lookup
Parameters
| Parameter | Type | Description |
|---|---|---|
| langquery | string enum | Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default en. |
| lines*query | string | Six-digit binary pattern (0=yin/broken, 1=yang/solid) from bottom to top. |
Response
Structured JSON with documented fields, covered by 13,405 automated tests per deploy, 3,620 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.
{
"number": 1,
"symbol": "䷀",
"chinese": "乾",
"english": "The Creative",
"pinyin": "Qián",
"binary": "111111",
"upperTrigram": "Heaven",
"lowerTrigram": "Heaven",
"judgment": "Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.",
"image": "Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.",
"interpretation": {
"general": "A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance. This is the moment to begin, to lead, and to bring your vision into being.",
"love": "A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance. Let your confidence inspire trust rather than demand it.",
"career": "Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak. Step forward boldly but remain open to collaboration.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence. Success comes through perseverance and maintaining your integrity.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force. The greatest influence comes from inner alignment."
},
"changingLines": [
{
"position": 1,
"text": "The dragon lies hidden in the deep, and the time for action has not arrived.",
"meaning": "The force is genuine, but the first place is the lowest ground in the situation and nothing there can carry a move yet. A yang line asked to hold still receives the hardest instruction it can get, and obeying it is the whole test. Build capacity out of sight and let the conditions ripen."
},
{
"position": 2,
"text": "The dragon shows itself in the open field, and it is worth seeking out someone of standing.",
"meaning": "The second place is the center of the lower trigram, so this yang line is visible and supported rather than exposed. Influence starts to collect around the querent without having to be demanded. Meet the people who can widen the work and let competence do the announcing."
},
{
"position": 3,
"text": "Working through the whole day and still watchful at nightfall, in danger and yet without fault.",
"meaning": "The third place is the threshold between the trigrams, where a yang line has climbed out of shelter with nothing above it to break a fall. The exposure is real and it is survivable only through unbroken vigilance. Do the work, watch the ground, and assume nothing is secure."
},
{
"position": 4,
"text": "The dragon gathers itself to leap, still hovering over the depths.",
"meaning": "The fourth place sits directly beneath authority, so a yang line here may rise or may hold back, and both roads are open. Nobody will make the choice for the querent, and either choice is blameless if it is made deliberately. Decide from your own reading of the ground, never from impatience."
},
{
"position": 5,
"text": "The dragon flies in the open sky, and it is worth seeking out someone of standing.",
"meaning": "This is the ruling line, yang in the place of authority, so the force of the hexagram is fully expressed and correctly placed. Capacity and position coincide, which happens rarely and does not last. Act at scale while the alignment holds and draw capable people to you."
},
{
"position": 6,
"text": "The dragon has climbed past its limit and finds nothing above it, and there is cause for regret.",
"meaning": "The sixth place is past the peak, and a yang line here keeps pushing after the situation has stopped rewarding the push. Ambition that has lost contact with the ground produces the fall it never calculated. Stop climbing and return to a scale that can actually be held."
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
| number* | number | Hexagram number in the traditional King Wen sequence (1-64), the standard ordering used in I-Ching divination for over 3,000 years. |
| symbol* | string | Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces. |
| chinese* | string | Original Chinese character name of the hexagram in traditional script. |
| english* | string | English translation of the hexagram name, conveying the core concept and life situation it represents. |
| pinyin* | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
| binary* | string | Binary line pattern (6 digits, bottom to top). 1 = yang (solid line), 0 = yin (broken line). Lines 1-3 form the lower trigram, lines 4-6 form the upper trigram. |
| upperTrigram* | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
| lowerTrigram* | string | Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning. |
| judgment* | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome. |
| image* | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action. |
| interpretation* | object | |
| interpretation.general* | string | General life situation interpretation of this hexagram. |
| interpretation.love* | string | Love and relationship guidance from this hexagram. |
| interpretation.career* | string | Career and professional life interpretation. |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| interpretation.decision* | string | Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram. |
| interpretation.advice* | string | Practical wisdom and actionable advice from this hexagram for daily life application. |
| changingLines* | array of object | Changing line interpretations for all 6 lines |
| changingLines[].position* | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
| changingLines[].text* | string | The oracle statement for this line. It applies when this specific line comes up changing (old yin or old yang) in a casting, and it speaks in the concrete imagery of the tradition. |
| changingLines[].meaning | string | What the line statement asks of the querent, read from its position in the hexagram (1 is the hidden beginning, 3 is the exposed threshold, 5 is the ruling line, 6 is past the peak) and from whether the line is yin or yang. This is the meaning behind the image, so a consuming agent does not have to invent one. |
Supported options
lang
Call it in your language.
Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.lookupHexagram({ query: { lines: '111111' } })Install: npm install @roxyapi/sdk
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.lookup_hexagram(lines='111111')Install: pip install roxy-sdk
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->lookupHexagram(lines: '111111');Install: composer require roxyapi/sdk
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Hexagrams.Lookup.GetAsync();Install: dotnet add package RoxyApi.Sdk
import roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Iching.LookupHexagram(ctx, nil)Install: go get github.com/RoxyAPI/sdk-go
curl "https://roxyapi.com/api/v2/iching/hexagrams/lookup?lines=111111" \
-H "X-API-Key: YOUR_KEY"Prefer to try before you write code? Run this I-Ching endpoint live in the API playground and inspect a real production response.
More I Ching Hexagram endpoints
The I Ching Hexagram API bundles these related endpoints under one key.
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 liveGet 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 liveRandom 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 liveRemote MCP for AI agents
Every I-Ching endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.
claude mcp add --transport http \
roxy-iching https://roxyapi.com/mcp/iching \
--header "X-API-Key: YOUR_KEY"Tool name for GET /iching/hexagrams/lookup: get_iching_hexagrams_lookup. Full MCP setup guide
What you can build
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
Drop-in UI components and no-code widgets.
Render I Ching Hexagram 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 Hexagram API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.
Show all I Ching Hexagram UI componentsShow fewer I Ching Hexagram UI components
| Element | Renders |
|---|---|
| <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 |
Related capabilities
I Ching Hexagram API FAQ
What does the I Ching Hexagram API return?
Find an I-Ching hexagram by its binary line pattern. Every response is structured JSON with documented fields, not free text, so you map it straight into your product.
How do I authenticate with the I Ching Hexagram API?
Pass your key in the X-API-Key header on every request. Keys are delivered instantly at checkout with no approval queue. Use a secret sk key server side, or mint a publishable pk key locked to your origins for browser and no-code use.
Does the I Ching Hexagram API support multiple languages?
Yes. Append the lang query parameter to any endpoint for responses in English, German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The translated payload includes the full interpretation text, not just field labels.
Is the I Ching Hexagram API available over Remote MCP for AI agents?
Yes. Every endpoint is exposed as a callable tool on the Remote MCP server at https://roxyapi.com/mcp/iching over Streamable HTTP, so Claude, ChatGPT, Cursor, and any MCP client auto-discover it with no local setup or Docker.
How is the I Ching Hexagram API billed?
Flat pricing: 1 request equals 1 quota unit, REST and MCP identical, with no credit weighting or per-token markup. Every plan includes all 18 domains, so the I Ching Hexagram API is included at no extra cost.
Start using I Ching Hexagram 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
