I Ching API, what to build and how to call it

Ship an I Ching oracle, a daily hexagram widget, or a decision-making chatbot in under 20 minutes. 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. Roxy returns hexagrams with judgment text, image text, and per-area interpretation (general, love, career, decision, advice). i ching API, hexagram API, and cast hexagram online are the search keywords.

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 Roxy API key. Get one on the pricing page.
2. Nothing else. No birth data, no account sync.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require 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 } = await roxy.iching.castReading({
  query: { seed: 'user-42' },
});

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

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.

Render the result

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 changing-line readings.

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.

Ready-made starter

The /starters/astrology-ai-chatbot (multi-domain, covers I-Ching via Remote MCP) starter ships a working I-Ching app you can clone, white-label, and deploy in 30 minutes. 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.