I Ching API guide

Ship an I Ching oracle, a daily hexagram widget, or a decision-making chatbot. 64 hexagrams, ready interpretations.

The I Ching (Book of Changes) is the 3000-year-old Chinese oracle of 64 hexagrams. Each hexagram is six lines (broken or solid) representing a life situation with guidance. RoxyAPI returns hexagrams with judgment text, image text, and per-area interpretation (general, love, career, decision, advice). Cast a hexagram, look one up by number, or pull a stable daily reading, all from one key.

What you can build

• Oracle apps that cast a hexagram for the user question
• Daily hexagram widgets for meditation and wellness apps
• Decision-making tools, "should I do X" chatbot answers
• Reference apps browsing all 64 hexagrams and the 8 trigrams

Prerequisites

1. A RoxyAPI key. Get your API key.
2. Nothing else. No birth data, no account sync.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

Call the endpoint

The #1 I Ching call is casting a reading. GET /iching/cast simulates the three-coin toss, returns the primary hexagram, which lines are changing, and the transformed hexagram. Pick a language.

curl "https://roxyapi.com/api/v2/iching/cast?seed=user-42" \
  -H "X-API-Key: $ROXY_API_KEY"

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data, error } = await roxy.iching.castReading({
  query: { seed: 'user-42' },
});
if (error) throw error;

console.log(data.hexagram?.english);       // "Peace"
console.log(data.changingLinePositions);   // e.g. [2, 5]
console.log(data.resultingHexagram?.english);

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

reading = roxy.iching.cast_reading(seed='user-42')
print(reading['hexagram']['english'])
print(reading.get('changingLinePositions'))

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$reading = $roxy->iching->castReading(seed: 'user-42');
echo $reading['hexagram']['english'];
print_r($reading['changingLinePositions'] ?? null);

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var reading = await roxy.Iching.Cast.GetAsync(c => c.QueryParameters.Seed = "user-42");

Console.WriteLine(reading!.Hexagram!.English);                               // "Peace"
Console.WriteLine(string.Join(", ", reading.ChangingLinePositions ?? new())); // e.g. 2, 5
Console.WriteLine(reading.ResultingHexagram?.English);

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

The response returns the primary hexagram with symbol, Chinese character, pinyin, trigrams, judgment, image, and interpretation block, plus the changing-line positions (array of 1 to 6 indexes from the bottom) and a resulting hexagram when lines change. Every changing line carries both its oracle statement (text) and what that statement asks of the querent (meaning), read from the line position and its yin or yang, so an agent does not have to invent the reading.

Render the result

Understand the six line values

The three-coin method assigns 2 to tails and 3 to heads, then adds the three coins for each line. Build the figure from bottom to top:

Three lines form a trigram; two trigrams form a hexagram. Read the primary figure, then the changing-line text, then the resulting figure as a symbolic progression. It is a reflection framework, not a guaranteed outcome. Save the complete response with any journal entry that must remain unchanged after future API updates.

A hexagram reading has an arc: the present hexagram, the changing lines, and the transformed hexagram as the outcome. The @roxyapi/ui library ships RoxyHexagram, which draws the six lines, highlights the changing ones, and shows the trigrams, judgment, image, and resulting hexagram from the same response shape. Pass the unwrapped data straight in.

'use client';
import { RoxyHexagram } from '@roxyapi/ui-react';
import type { GetIchingCastResponse } from '@roxyapi/sdk';

export function HexagramReading({ data }: { data: GetIchingCastResponse }) {
  return <RoxyHexagram data={data} mode="cast" />;
}

data is the unwrapped SDK response (const { data } = await roxy.iching.castReading(...)), and its type GetIchingCastResponse comes from @roxyapi/sdk. The component reads hexagram, changingLinePositions, and resultingHexagram for you, so there is no per-field markup to maintain. For a fetched-by-number or daily reading, set mode="lookup" or mode="daily".

Ship the rest

Daily hexagram, the widget feature

POST /iching/daily returns the hexagram for the day with an optional per-user seed. Same seed plus same date produces the same hexagram, stable for push notifications.

Seeded daily cast

POST /iching/daily/cast is the three-coin-toss version of daily. Stable for the day, includes changing lines.

The 64 hexagrams

GET /iching/hexagrams returns the full list (cache once, browse offline). GET /iching/hexagrams/{number} returns one hexagram by its King Wen number (1 to 64) with full content: symbol, Chinese, pinyin, trigrams, judgment, image, interpretation (general, love, career, decision, advice), and all six changing lines with the oracle statement and its meaning.

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

See the full list at the I Ching API reference.

Explore the eight trigrams

GET /iching/trigrams provides the eight three-line figures used to build hexagrams. A reference screen can pair the lower and upper trigram with the full six-line figure, helping a reader understand the composition before opening the interpretation.

Ready-made template

The /templates/astrology-ai-chatbot (multi-domain, covers I-Ching via Remote MCP) template ships a working I-Ching app you can clone, white-label, and deploy. MIT licensed. For the render layer, see the component catalog in @roxyapi/ui.

Gotchas

• Hexagram numbering is King Wen 1 to 64. Not zero-indexed.
• Changing lines use positions 1 through 6 from the bottom. changingLinePositions: [2, 5] means the second and fifth lines (counting up) are changing. Match your rendering to this ordering.
• resultingHexagram is null when no lines change. Guard before rendering.
• Seeded daily endpoints are deterministic per (seed, date). Do not retry on identical responses, that is the feature.
• Cast uses GET, daily uses POST. The live cast endpoint takes query params (seed, lang), the seeded daily endpoints take a JSON body.

What to build next

The AI chatbot tutorial shows how an agent picks the I Ching cast tool when a user asks a "should I do X" question. For a static daily widget, adapt the daily horoscope widget tutorial to call /iching/daily instead. Typed calls live in the SDK guide.