I-Ching API Reference

I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career, and decision-making.

Product page

Base URL: https://roxyapi.com/api/v2/iching
Remote MCP: https://roxyapi.com/mcp/iching
OpenAPI: https://roxyapi.com/api/v2/iching/openapi.json
Auth: X-API-Key
Languages: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant
SDKs: TypeScript, Python, PHP, C#, Go, and Rust

POST /api/v2/iching/daily

Daily hexagram

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.

MCP tool: post_iching_daily
Renders with: Hexagram · No-code widget

Request

Show all 3 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.
seed string: Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token) to give each user their own hexagram for the day. Without a seed every caller receives the same shared hexagram of the day.
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.

Response

date string, required

Date this daily hexagram is for (YYYY-MM-DD, UTC).

seed string, required

Computed seed used for this reading. Same seed always produces the same hexagram.

hexagram object, required

Show all 15 fieldsShow fewer fields

number number, required: Hexagram number in King Wen sequence (1-64).
symbol string, required: Unicode hexagram symbol for display.
chinese string, required: Original Chinese name.
english string, required: English translation of the hexagram name.
pinyin string, required: Pinyin romanization with tone marks.
upperTrigram string, required: Upper trigram (lines 4-6).
lowerTrigram string, required: Lower trigram (lines 1-3).
judgment string, required: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance.
image string, required: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action.
interpretation object, required: Modern interpretations across life areas based on ancient I-Ching wisdom.
interpretation.general string, required: General life situation interpretation.
interpretation.love string, required: Love and relationship guidance.
interpretation.career string, required: Career and professional interpretation.
interpretation.decision string, required: Decision-making guidance for whether to act, wait, or change course.
interpretation.advice string, required: Practical wisdom and actionable advice.

dailyMessage string, required

Concise daily message summarizing the hexagram guidance

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /iching/daily

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.getDailyHexagram({ body: { seed: 'user123', date: '2026-03-06' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.get_daily_hexagram(seed='user123', date='2026-03-06')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->getDailyHexagram(seed: 'user123', date: '2026-03-06');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Daily.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Iching.GetDailyHexagram(ctx, nil, roxyapi.GetDailyHexagramJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GetDailyHexagramParams, body: &types::GetDailyHexagramRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().get_daily_hexagram(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

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"}'

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

POST /api/v2/iching/daily/cast

Cast daily reading with changing lines

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.

MCP tool: post_iching_daily_cast
Renders with: Hexagram · No-code widget

Request

Show all 3 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.
seed string: Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token) to give each user their own hexagram for the day. Without a seed every caller receives the same shared hexagram of the day.
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.

Response

date string, required

Date this daily casting is for (YYYY-MM-DD, UTC).

seed string, required

Computed seed for reproducible castings.

hexagram object

Show all 20 fieldsShow fewer fields

number number, required: Hexagram number in King Wen sequence (1-64).
symbol string, required: Unicode hexagram symbol for display.
chinese string, required: Original Chinese name.
english string, required: English translation of the hexagram name.
pinyin string, required: Pinyin romanization with tone marks.
upperTrigram string, required: Upper trigram (lines 4-6).
lowerTrigram string, required: Lower trigram (lines 1-3).
judgment string, required: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance.
image string, required: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action.
interpretation object, required: Modern interpretations across life areas based on ancient I-Ching wisdom.
interpretation.general string, required: General life situation interpretation.
interpretation.love string, required: Love and relationship guidance.
interpretation.career string, required: Career and professional interpretation.
interpretation.decision string, required: Decision-making guidance for whether to act, wait, or change course.
interpretation.advice string, required: Practical wisdom and actionable advice.
binary string, required: 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.
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 number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
changingLines[].text string, required: 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.

lines array of number, required

Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing).

changingLinePositions array of number, required

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.

Show all 3 fieldsShow fewer fields

position number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
text string, required: 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.
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)

Show all 15 fieldsShow fewer fields

number number, required: Hexagram number in King Wen sequence (1-64).
symbol string, required: Unicode hexagram symbol for display.
chinese string, required: Original Chinese name.
english string, required: English translation of the hexagram name.
pinyin string, required: Pinyin romanization with tone marks.
upperTrigram string, required: Upper trigram (lines 4-6).
lowerTrigram string, required: Lower trigram (lines 1-3).
judgment string, required: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance.
image string, required: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action.
interpretation object, required: Modern interpretations across life areas based on ancient I-Ching wisdom.
interpretation.general string, required: General life situation interpretation.
interpretation.love string, required: Love and relationship guidance.
interpretation.career string, required: Career and professional interpretation.
interpretation.decision string, required: Decision-making guidance for whether to act, wait, or change course.
interpretation.advice string, required: Practical wisdom and actionable advice.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /iching/daily/cast

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.castDailyReading({ body: { seed: 'user123', date: '2026-03-06' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.cast_daily_reading(seed='user123', date='2026-03-06')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->castDailyReading(seed: 'user123', date: '2026-03-06');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Daily.Cast.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Iching.CastDailyReading(ctx, nil, roxyapi.CastDailyReadingJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::CastDailyReadingParams, body: &types::CastDailyReadingRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().cast_daily_reading(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

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"}'

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/hexagrams

List all 64 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.

MCP tool: get_iching_hexagrams

Request

Show all 3 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. 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.

Response

total number, required

Total number of I-Ching hexagrams (always 64).

limit number, required

Page size used for this response.

offset number, required

Number of hexagrams skipped. Use with limit for pagination.

hexagrams array of object, required

Hexagrams for the current page. Use /hexagrams/{number} for full details.

Show all 7 fieldsShow fewer fields

number number, required: Hexagram number in King Wen sequence (1-64).
symbol string, required: Unicode hexagram symbol for display.
chinese string, required: Original Chinese name of the hexagram.
english string, required: English translation of the hexagram name.
pinyin string, required: Pinyin romanization of the Chinese name with tone marks.
upperTrigram string, required: Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake.
lowerTrigram string, required: Lower trigram (lines 1-3). Combines with upper trigram to form the hexagram.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/hexagrams

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.listHexagrams()

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.list_hexagrams()

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->listHexagrams();

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Hexagrams.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.ListHexagrams(ctx, nil)

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::ListHexagramsParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().list_hexagrams(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/hexagrams" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/hexagrams/random

Random hexagram

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.

MCP tool: get_iching_hexagrams_random
Renders with: Hexagram · No-code widget

Request

Show all 1 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.

Response

number number, required

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, required

Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces.

chinese string, required

Original Chinese character name of the hexagram in traditional script.

english string, required

English translation of the hexagram name, conveying the core concept and life situation it represents.

pinyin string, required

Pinyin romanization of the Chinese name with tone marks for correct pronunciation.

binary string, required

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, required

Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake.

lowerTrigram string, required

Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning.

judgment string, required

The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome.

image string, required

The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action.

interpretation object, required

Show all 5 fieldsShow fewer fields

general string, required: General life situation interpretation of this hexagram.
love string, required: Love and relationship guidance from this hexagram.
career string, required: Career and professional life interpretation.
decision string, required: Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram.
advice string, required: Practical wisdom and actionable advice from this hexagram for daily life application.

changingLines array of object, required

Changing line interpretations for all 6 lines

Show all 3 fieldsShow fewer fields

position number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
text string, required: 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.
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.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`404`	No hexagrams available.
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/hexagrams/random

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.getRandomHexagram()

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.get_random_hexagram()

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->getRandomHexagram();

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Hexagrams.Random.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.GetRandomHexagram(ctx, nil)

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GetRandomHexagramParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().get_random_hexagram(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/hexagrams/random" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/hexagrams/lookup

Lookup hexagram by line pattern

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

MCP tool: get_iching_hexagrams_lookup
Renders with: Hexagram · No-code widget

Request

lines query, string, required: Six-digit binary pattern (0=yin/broken, 1=yang/solid) from bottom to top.

Show all 1 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.

Response

number number, required

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, required

Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces.

chinese string, required

Original Chinese character name of the hexagram in traditional script.

english string, required

English translation of the hexagram name, conveying the core concept and life situation it represents.

pinyin string, required

Pinyin romanization of the Chinese name with tone marks for correct pronunciation.

binary string, required

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, required

Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake.

lowerTrigram string, required

Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning.

judgment string, required

The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome.

image string, required

The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action.

interpretation object, required

Show all 5 fieldsShow fewer fields

general string, required: General life situation interpretation of this hexagram.
love string, required: Love and relationship guidance from this hexagram.
career string, required: Career and professional life interpretation.
decision string, required: Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram.
advice string, required: Practical wisdom and actionable advice from this hexagram for daily life application.

changingLines array of object, required

Changing line interpretations for all 6 lines

Show all 3 fieldsShow fewer fields

position number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
text string, required: 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.
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.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`404`	No hexagram found for pattern.
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/hexagrams/lookup

TypeScript

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

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.lookup_hexagram(lines='111111')

Install: pip install roxy-sdk

PHP

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

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::LookupHexagramParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().lookup_hexagram(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/hexagrams/lookup?lines=111111" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/hexagrams/{number}

Get hexagram by 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.

MCP tool: get_iching_hexagrams_number
Renders with: Hexagram · No-code widget

Request

number path, integer, required: Hexagram number in King Wen sequence (1-64).

Show all 1 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.

Response

number number, required

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, required

Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces.

chinese string, required

Original Chinese character name of the hexagram in traditional script.

english string, required

English translation of the hexagram name, conveying the core concept and life situation it represents.

pinyin string, required

Pinyin romanization of the Chinese name with tone marks for correct pronunciation.

binary string, required

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, required

Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake.

lowerTrigram string, required

Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning.

judgment string, required

The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome.

image string, required

The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action.

interpretation object, required

Show all 5 fieldsShow fewer fields

general string, required: General life situation interpretation of this hexagram.
love string, required: Love and relationship guidance from this hexagram.
career string, required: Career and professional life interpretation.
decision string, required: Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram.
advice string, required: Practical wisdom and actionable advice from this hexagram for daily life application.

changingLines array of object, required

Changing line interpretations for all 6 lines

Show all 3 fieldsShow fewer fields

position number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
text string, required: 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.
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.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`404`	Hexagram not found.
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/hexagrams/{number}

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.getHexagram({ path: { number: 1 } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.get_hexagram(number=1)

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->getHexagram(number: 1);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Hexagrams["1"].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.GetHexagram(ctx, "1", nil)

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GetHexagramParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().get_hexagram(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/hexagrams/1" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/cast

Cast an I-Ching reading

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.

MCP tool: get_iching_cast
Renders with: Hexagram · No-code widget

Request

Show all 2 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. 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.

Response

seed string

The seed used for this casting (if provided)

hexagram object

Show all 20 fieldsShow fewer fields

number number, required: 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, required: Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces.
chinese string, required: Original Chinese character name of the hexagram in traditional script.
english string, required: English translation of the hexagram name, conveying the core concept and life situation it represents.
pinyin string, required: Pinyin romanization of the Chinese name with tone marks for correct pronunciation.
binary string, required: 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, required: Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake.
lowerTrigram string, required: Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning.
judgment string, required: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome.
image string, required: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action.
interpretation object, required
interpretation.general string, required: General life situation interpretation of this hexagram.
interpretation.love string, required: Love and relationship guidance from this hexagram.
interpretation.career string, required: Career and professional life interpretation.
interpretation.decision string, required: Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram.
interpretation.advice string, required: Practical wisdom and actionable advice from this hexagram for daily life application.
changingLines array of object, required: Changing line interpretations for all 6 lines
changingLines[].position number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
changingLines[].text string, required: 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.

lines array of number, required

Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing)

changingLinePositions array of number, required

Positions of changing lines (1-6, bottom to top)

resultingHexagram object

Show all 20 fieldsShow fewer fields

number number, required: 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, required: Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces.
chinese string, required: Original Chinese character name of the hexagram in traditional script.
english string, required: English translation of the hexagram name, conveying the core concept and life situation it represents.
pinyin string, required: Pinyin romanization of the Chinese name with tone marks for correct pronunciation.
binary string, required: 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, required: Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake.
lowerTrigram string, required: Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning.
judgment string, required: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome.
image string, required: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action.
interpretation object, required
interpretation.general string, required: General life situation interpretation of this hexagram.
interpretation.love string, required: Love and relationship guidance from this hexagram.
interpretation.career string, required: Career and professional life interpretation.
interpretation.decision string, required: Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram.
interpretation.advice string, required: Practical wisdom and actionable advice from this hexagram for daily life application.
changingLines array of object, required: Changing line interpretations for all 6 lines
changingLines[].position number, required: Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward.
changingLines[].text string, required: 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.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/cast

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.castReading()

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.cast_reading()

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->castReading();

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Cast.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.CastReading(ctx, nil)

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::CastReadingParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().cast_reading(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/cast" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/trigrams

List all 8 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.

MCP tool: get_iching_trigrams

Request

Show all 1 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.

Response

total number, required

Total number of I-Ching trigrams (always 8).

trigrams array of object, required

All 8 trigrams (bagua) with basic details.

Show all 7 fieldsShow fewer fields

number number, required: Trigram number (1-8)
symbol string, required: Unicode trigram symbol
chinese string, required: Chinese name
english string, required: English name
pinyin string, required: Pinyin romanization
binary string, required: Binary representation (1=Yang solid, 0=Yin broken)
attribute string, required: Core attribute/quality

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/trigrams

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.listTrigrams()

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.list_trigrams()

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->listTrigrams();

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Trigrams.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.ListTrigrams(ctx, nil)

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::ListTrigramsParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().list_trigrams(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/trigrams" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'

GET /api/v2/iching/trigrams/{id}

Get trigram by number or name

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.

MCP tool: get_iching_trigrams_id
Renders with: Reference card · No-code widget

Request

id path, string, required: Trigram number (1-8) or English name (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake).

Show all 1 optional fieldsShow fewer optional fields

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. One of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Default en.

Response

number number, required: 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 string, required: Unicode trigram symbol (three lines) for visual display in I-Ching interfaces and Bagua diagrams.
chinese string, required: Original Chinese character name of the trigram in traditional script.
english string, required: English name representing the natural force or element this trigram embodies.
pinyin string, required: Pinyin romanization of the Chinese name with tone marks for correct pronunciation.
binary string, required: Three-digit binary representation of the trigram lines (bottom to top). 1 = yang (solid), 0 = yin (broken).
element string, required: Five element (Wu Xing) correspondence: Metal, Wood, Water, Fire, or Earth. Used in Chinese metaphysics and feng shui analysis.
attribute string, required: Core attribute or quality this trigram represents in I-Ching philosophy (e.g., Creative, Receptive, Arousing).
familyMember string, required: Family archetype in the Bagua system. Each trigram corresponds to a family role (Father, Mother, First Son, First Daughter, etc.).
direction string, required: Compass direction in the King Wen (Later Heaven) Bagua arrangement. Used in feng shui spatial analysis.
bodyPart string, required: Body part associated with this trigram in traditional Chinese medicine and I-Ching body mapping.
animal string, required: Animal symbol associated with this trigram in classical I-Ching imagery and divination.
season string, required: Season or time period associated with this trigram in the annual cycle of Chinese cosmology.
quality string, required: Energetic quality describing the dynamic nature of this trigram (e.g., Strong, Devoted, Joyous, Gentle).
meaning string, required: Concise interpretation of the trigram covering its symbolic meaning, key associations, and guidance for understanding hexagrams containing this trigram.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`404`	Trigram not found.
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

GET /iching/trigrams/{id}

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.getTrigram({ path: { id: 'Heaven' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.iching.get_trigram(id='Heaven')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->getTrigram(id: 'Heaven');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Trigrams["Heaven"].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.GetTrigram(ctx, "Heaven", nil)

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GetTrigramParams) -> Result<(), roxyapi::Error> {
    let result = roxy.iching().get_trigram(params).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl "https://roxyapi.com/api/v2/iching/trigrams/Heaven" \
  -H "X-API-Key: YOUR_KEY"

MCP

claude mcp add-json roxy-iching '{"type":"http","url":"https://roxyapi.com/mcp/iching","headers":{"X-API-Key":"YOUR_KEY"}}'