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.
9 endpoints. Product page. Typed SDKs in six languages carry every operation below.
POST /api/v2/iching/daily
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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| Field | Type | Description |
|---|---|---|
seed | string | Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings. |
date | string (date) | Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones. |
curl -X POST "https://roxyapi.com/api/v2/iching/daily" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"seed":"user123","date":"2026-03-06"}'| Field | Type | Description |
|---|---|---|
date required | string | Date this daily hexagram is for (YYYY-MM-DD, UTC). |
seed required | string | Computed seed used for this reading. Same seed always produces the same hexagram. |
hexagram required | object | |
hexagram.number required | number | Hexagram number in King Wen sequence (1-64). |
hexagram.symbol required | string | Unicode hexagram symbol for display. |
hexagram.chinese required | string | Original Chinese name. |
hexagram.english required | string | English translation of the hexagram name. |
hexagram.pinyin required | string | Pinyin romanization with tone marks. |
hexagram.upperTrigram required | string | Upper trigram (lines 4-6). |
hexagram.lowerTrigram required | string | Lower trigram (lines 1-3). |
hexagram.judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance. |
hexagram.image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action. |
hexagram.interpretation required | object | Modern interpretations across life areas based on ancient I-Ching wisdom. |
hexagram.interpretation.general required | string | General life situation interpretation. |
| Field | Type | Description |
|---|---|---|
hexagram.interpretation.love required | string | Love and relationship guidance. |
hexagram.interpretation.career required | string | Career and professional interpretation. |
hexagram.interpretation.decision required | string | Decision-making guidance for whether to act, wait, or change course. |
hexagram.interpretation.advice required | string | Practical wisdom and actionable advice. |
dailyMessage required | string | Concise daily message summarizing the hexagram guidance |
{
"date": "2026-01-28",
"seed": "user123-2026-01-28",
"hexagram": {
"number": 1,
"symbol": "䷀",
"chinese": "乾",
"english": "The Creative",
"pinyin": "Qián",
"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.",
"love": "A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.",
"career": "Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force."
}
},
"dailyMessage": "Your hexagram for 2026-01-28: The Creative (乾). Be like the heavens: consistent, powerful, and untiring."
}POST /api/v2/iching/daily/cast
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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
| Field | Type | Description |
|---|---|---|
seed | string | Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings. |
date | string (date) | Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones. |
curl -X POST "https://roxyapi.com/api/v2/iching/daily/cast" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"seed":"user123","date":"2026-03-06"}'| Field | Type | Description |
|---|---|---|
date required | string | Date this daily casting is for (YYYY-MM-DD, UTC). |
seed required | string | Computed seed for reproducible castings. |
hexagram | object | |
hexagram.number required | number | Hexagram number in King Wen sequence (1-64). |
hexagram.symbol required | string | Unicode hexagram symbol for display. |
hexagram.chinese required | string | Original Chinese name. |
hexagram.english required | string | English translation of the hexagram name. |
hexagram.pinyin required | string | Pinyin romanization with tone marks. |
hexagram.upperTrigram required | string | Upper trigram (lines 4-6). |
hexagram.lowerTrigram required | string | Lower trigram (lines 1-3). |
hexagram.judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance. |
hexagram.image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action. |
hexagram.interpretation required | object | Modern interpretations across life areas based on ancient I-Ching wisdom. |
hexagram.interpretation.general required | string | General life situation interpretation. |
| Field | Type | Description |
|---|---|---|
hexagram.interpretation.love required | string | Love and relationship guidance. |
hexagram.interpretation.career required | string | Career and professional interpretation. |
hexagram.interpretation.decision required | string | Decision-making guidance for whether to act, wait, or change course. |
hexagram.interpretation.advice required | string | Practical wisdom and actionable advice. |
hexagram.binary required | 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. |
hexagram.changingLines | array of object | The oracle statement and meaning of each line that came up CHANGING, and only those. The changing lines are what the cast is actually about, so this saves a second call to read them and stops a consuming agent from having to invent them. |
hexagram.changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
hexagram.changingLines[].text required | 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. |
hexagram.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. |
lines required | array of number | Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing). |
changingLinePositions required | array of number | Positions of changing lines (1-6, bottom to top). These lines transform yin to yang or vice versa. |
changingLines | array of object | The oracle statement and meaning of each line that came up CHANGING, and only those. The changing lines are what the cast is actually about, so this saves a second call to read them and stops a consuming agent from having to invent them. |
changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
changingLines[].text required | 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. |
resultingHexagram | object | Hexagram after transformation (if changing lines present) |
resultingHexagram.number required | number | Hexagram number in King Wen sequence (1-64). |
resultingHexagram.symbol required | string | Unicode hexagram symbol for display. |
resultingHexagram.chinese required | string | Original Chinese name. |
resultingHexagram.english required | string | English translation of the hexagram name. |
resultingHexagram.pinyin required | string | Pinyin romanization with tone marks. |
resultingHexagram.upperTrigram required | string | Upper trigram (lines 4-6). |
resultingHexagram.lowerTrigram required | string | Lower trigram (lines 1-3). |
resultingHexagram.judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance. |
resultingHexagram.image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action. |
resultingHexagram.interpretation required | object | Modern interpretations across life areas based on ancient I-Ching wisdom. |
resultingHexagram.interpretation.general required | string | General life situation interpretation. |
resultingHexagram.interpretation.love required | string | Love and relationship guidance. |
resultingHexagram.interpretation.career required | string | Career and professional interpretation. |
resultingHexagram.interpretation.decision required | string | Decision-making guidance for whether to act, wait, or change course. |
resultingHexagram.interpretation.advice required | string | Practical wisdom and actionable advice. |
{
"date": "2026-01-28",
"seed": "user123-2026-01-28",
"hexagram": {
"number": 1,
"symbol": "䷀",
"chinese": "乾",
"english": "The Creative",
"pinyin": "Qián",
"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.",
"love": "A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.",
"career": "Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force."
},
"binary": "111111",
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
]
},
"lines": [
7,
8
],
"changingLinePositions": [
3,
5
],
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
],
"resultingHexagram": {
"number": 1,
"symbol": "䷀",
"chinese": "乾",
"english": "The Creative",
"pinyin": "Qián",
"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.",
"love": "A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.",
"career": "Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force."
}
}
}GET /api/v2/iching/hexagrams
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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
limit query | integer | Maximum items to return per page. Range: 1-64, default 20. Default 20. |
offset query | integer | Number of items to skip for pagination. Default 0. Default 0. |
curl "https://roxyapi.com/api/v2/iching/hexagrams" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
total required | number | Total number of I-Ching hexagrams (always 64). |
limit required | number | Page size used for this response. |
offset required | number | Number of hexagrams skipped. Use with limit for pagination. |
hexagrams required | array of object | Hexagrams for the current page. Use /hexagrams/{number} for full details. |
hexagrams[].number required | number | Hexagram number in King Wen sequence (1-64). |
hexagrams[].symbol required | string | Unicode hexagram symbol for display. |
hexagrams[].chinese required | string | Original Chinese name of the hexagram. |
hexagrams[].english required | string | English translation of the hexagram name. |
hexagrams[].pinyin required | string | Pinyin romanization of the Chinese name with tone marks. |
hexagrams[].upperTrigram required | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
hexagrams[].lowerTrigram required | string | Lower trigram (lines 1-3). Combines with upper trigram to form the hexagram. |
{
"total": 64,
"limit": 20,
"offset": 0,
"hexagrams": [
{
"number": 1,
"symbol": "䷀",
"chinese": "乾",
"english": "The Creative",
"pinyin": "Qián",
"upperTrigram": "Heaven",
"lowerTrigram": "Heaven"
}
]
}GET /api/v2/iching/hexagrams/random
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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
curl "https://roxyapi.com/api/v2/iching/hexagrams/random" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
number required | 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 required | string | Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces. |
chinese required | string | Original Chinese character name of the hexagram in traditional script. |
english required | string | English translation of the hexagram name, conveying the core concept and life situation it represents. |
pinyin required | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
binary required | 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 required | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
lowerTrigram required | string | Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning. |
judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome. |
image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action. |
interpretation required | object | |
interpretation.general required | string | General life situation interpretation of this hexagram. |
interpretation.love required | string | Love and relationship guidance from this hexagram. |
interpretation.career required | string | Career and professional life interpretation. |
| Field | Type | Description |
|---|---|---|
interpretation.decision required | string | Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram. |
interpretation.advice required | string | Practical wisdom and actionable advice from this hexagram for daily life application. |
changingLines required | array of object | Changing line interpretations for all 6 lines |
changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
changingLines[].text required | 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. |
{
"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": "This hexagram represents the primal power of creation and the energy of pure initiative.",
"love": "A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.",
"career": "Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort."
},
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
]
}GET /api/v2/iching/hexagrams/lookup
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).
| Parameter | Type | Description |
|---|---|---|
lang query | 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 required query | string | Six-digit binary pattern (0=yin/broken, 1=yang/solid) from bottom to top. |
curl "https://roxyapi.com/api/v2/iching/hexagrams/lookup?lines=111111" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
number required | 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 required | string | Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces. |
chinese required | string | Original Chinese character name of the hexagram in traditional script. |
english required | string | English translation of the hexagram name, conveying the core concept and life situation it represents. |
pinyin required | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
binary required | 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 required | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
lowerTrigram required | string | Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning. |
judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome. |
image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action. |
interpretation required | object | |
interpretation.general required | string | General life situation interpretation of this hexagram. |
interpretation.love required | string | Love and relationship guidance from this hexagram. |
interpretation.career required | string | Career and professional life interpretation. |
| Field | Type | Description |
|---|---|---|
interpretation.decision required | string | Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram. |
interpretation.advice required | string | Practical wisdom and actionable advice from this hexagram for daily life application. |
changingLines required | array of object | Changing line interpretations for all 6 lines |
changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
changingLines[].text required | 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. |
{
"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": "This hexagram represents the primal power of creation and the energy of pure initiative.",
"love": "A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.",
"career": "Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort."
},
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
]
}GET /api/v2/iching/hexagrams/{number}
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.
| Parameter | Type | Description |
|---|---|---|
number required path | integer | Hexagram number in King Wen sequence (1-64). |
lang query | 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. |
curl "https://roxyapi.com/api/v2/iching/hexagrams/1" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
number required | 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 required | string | Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces. |
chinese required | string | Original Chinese character name of the hexagram in traditional script. |
english required | string | English translation of the hexagram name, conveying the core concept and life situation it represents. |
pinyin required | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
binary required | 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 required | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
lowerTrigram required | string | Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning. |
judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome. |
image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action. |
interpretation required | object | |
interpretation.general required | string | General life situation interpretation of this hexagram. |
interpretation.love required | string | Love and relationship guidance from this hexagram. |
interpretation.career required | string | Career and professional life interpretation. |
| Field | Type | Description |
|---|---|---|
interpretation.decision required | string | Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram. |
interpretation.advice required | string | Practical wisdom and actionable advice from this hexagram for daily life application. |
changingLines required | array of object | Changing line interpretations for all 6 lines |
changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
changingLines[].text required | 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. |
{
"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": "This hexagram represents the primal power of creation and the energy of pure initiative.",
"love": "A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.",
"career": "Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort."
},
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
]
}GET /api/v2/iching/cast
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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
seed query | string | Optional seed for reproducible castings. Same seed = same casting every time. Pass any unique identifier (userId, session token, question hash). Omit for random casting. |
curl "https://roxyapi.com/api/v2/iching/cast" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
seed | string | The seed used for this casting (if provided) |
hexagram | object | |
hexagram.number required | number | Hexagram number in the traditional King Wen sequence (1-64), the standard ordering used in I-Ching divination for over 3,000 years. |
hexagram.symbol required | string | Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces. |
hexagram.chinese required | string | Original Chinese character name of the hexagram in traditional script. |
hexagram.english required | string | English translation of the hexagram name, conveying the core concept and life situation it represents. |
hexagram.pinyin required | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
hexagram.binary required | 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. |
hexagram.upperTrigram required | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
hexagram.lowerTrigram required | string | Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning. |
hexagram.judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome. |
hexagram.image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action. |
hexagram.interpretation required | object | |
hexagram.interpretation.general required | string | General life situation interpretation of this hexagram. |
| Field | Type | Description |
|---|---|---|
hexagram.interpretation.love required | string | Love and relationship guidance from this hexagram. |
hexagram.interpretation.career required | string | Career and professional life interpretation. |
hexagram.interpretation.decision required | string | Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram. |
hexagram.interpretation.advice required | string | Practical wisdom and actionable advice from this hexagram for daily life application. |
hexagram.changingLines required | array of object | Changing line interpretations for all 6 lines |
hexagram.changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
hexagram.changingLines[].text required | 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. |
hexagram.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. |
lines required | array of number | Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing) |
changingLinePositions required | array of number | Positions of changing lines (1-6, bottom to top) |
resultingHexagram | object | |
resultingHexagram.number required | number | Hexagram number in the traditional King Wen sequence (1-64), the standard ordering used in I-Ching divination for over 3,000 years. |
resultingHexagram.symbol required | string | Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces. |
resultingHexagram.chinese required | string | Original Chinese character name of the hexagram in traditional script. |
resultingHexagram.english required | string | English translation of the hexagram name, conveying the core concept and life situation it represents. |
resultingHexagram.pinyin required | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
resultingHexagram.binary required | 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. |
resultingHexagram.upperTrigram required | string | Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake. |
resultingHexagram.lowerTrigram required | string | Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning. |
resultingHexagram.judgment required | string | The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome. |
resultingHexagram.image required | string | The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action. |
resultingHexagram.interpretation required | object | |
resultingHexagram.interpretation.general required | string | General life situation interpretation of this hexagram. |
resultingHexagram.interpretation.love required | string | Love and relationship guidance from this hexagram. |
resultingHexagram.interpretation.career required | string | Career and professional life interpretation. |
resultingHexagram.interpretation.decision required | string | Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram. |
resultingHexagram.interpretation.advice required | string | Practical wisdom and actionable advice from this hexagram for daily life application. |
resultingHexagram.changingLines required | array of object | Changing line interpretations for all 6 lines |
resultingHexagram.changingLines[].position required | number | Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward. |
resultingHexagram.changingLines[].text required | 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. |
resultingHexagram.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. |
{
"seed": "user123-question1",
"hexagram": {
"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": "This hexagram represents the primal power of creation and the energy of pure initiative.",
"love": "A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.",
"career": "Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort."
},
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
]
},
"lines": [
7,
8
],
"changingLinePositions": [
3,
5
],
"resultingHexagram": {
"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": "This hexagram represents the primal power of creation and the energy of pure initiative.",
"love": "A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.",
"career": "Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.",
"decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
"advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort."
},
"changingLines": [
{
"position": 1,
"text": "The dragon is still hidden below the surface, so it does not act.",
"meaning": "The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build."
}
]
}
}GET /api/v2/iching/trigrams
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.
| Parameter | Type | Description |
|---|---|---|
lang query | 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. |
curl "https://roxyapi.com/api/v2/iching/trigrams" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
total required | number | Total number of I-Ching trigrams (always 8). |
trigrams required | array of object | All 8 trigrams (bagua) with basic details. |
trigrams[].number required | number | Trigram number (1-8) |
trigrams[].symbol required | string | Unicode trigram symbol |
trigrams[].chinese required | string | Chinese name |
trigrams[].english required | string | English name |
trigrams[].pinyin required | string | Pinyin romanization |
trigrams[].binary required | string | Binary representation (1=Yang solid, 0=Yin broken) |
trigrams[].attribute required | string | Core attribute/quality |
{
"total": 8,
"trigrams": [
{
"number": 1,
"symbol": "☰",
"chinese": "乾",
"english": "Heaven",
"pinyin": "Qián",
"binary": "111",
"attribute": "Creative"
}
]
}GET /api/v2/iching/trigrams/{id}
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.
| Parameter | Type | Description |
|---|---|---|
id required path | string | Trigram number (1-8) or English name (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake). |
lang query | 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. |
curl "https://roxyapi.com/api/v2/iching/trigrams/Heaven" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
number required | number | Stable identifier for the trigram, 1 to 8. This is our lookup key, not a canonical sequence: the tradition has several orderings (King Wen, Fu Xi, Earlier and Later Heaven) and they disagree, so do not read ranking or precedence into it. |
symbol required | string | Unicode trigram symbol (three lines) for visual display in I-Ching interfaces and Bagua diagrams. |
chinese required | string | Original Chinese character name of the trigram in traditional script. |
english required | string | English name representing the natural force or element this trigram embodies. |
pinyin required | string | Pinyin romanization of the Chinese name with tone marks for correct pronunciation. |
binary required | string | Three-digit binary representation of the trigram lines (bottom to top). 1 = yang (solid), 0 = yin (broken). |
element required | string | Five element (Wu Xing) correspondence: Metal, Wood, Water, Fire, or Earth. Used in Chinese metaphysics and feng shui analysis. |
attribute required | string | Core attribute or quality this trigram represents in I-Ching philosophy (e.g., Creative, Receptive, Arousing). |
familyMember required | string | Family archetype in the Bagua system. Each trigram corresponds to a family role (Father, Mother, First Son, First Daughter, etc.). |
direction required | string | Compass direction in the King Wen (Later Heaven) Bagua arrangement. Used in feng shui spatial analysis. |
bodyPart required | string | Body part associated with this trigram in traditional Chinese medicine and I-Ching body mapping. |
animal required | string | Animal symbol associated with this trigram in classical I-Ching imagery and divination. |
season required | string | Season or time period associated with this trigram in the annual cycle of Chinese cosmology. |
quality required | string | Energetic quality describing the dynamic nature of this trigram (e.g., Strong, Devoted, Joyous, Gentle). |
| Field | Type | Description |
|---|---|---|
meaning required | string | Concise interpretation of the trigram covering its symbolic meaning, key associations, and guidance for understanding hexagrams containing this trigram. |
{
"number": 1,
"symbol": "☰",
"chinese": "乾",
"english": "Heaven",
"pinyin": "Qián",
"binary": "111",
"element": "Metal",
"attribute": "Creative",
"familyMember": "Father",
"direction": "Northwest",
"bodyPart": "Head",
"animal": "Horse",
"season": "Late Autumn",
"quality": "Strong",
"meaning": "The Creative force representing pure yang energy, strength, leadership, and the power of initiative."
}Hi, I am Rosie, your guide to the RoxyAPI insight tools.
Ask me to read your birth chart, pull a card, or map your numbers, and I will interpret what it means for you. Unlike most AIs, I never make the numbers up: every reading runs on real, verified calculations. Curious about the API, pricing, or docs instead? Ask me that too.