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 with this

• 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

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page.
2. Nothing else. No birth data, no account sync.

Step 1, call your first 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'))

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.

Step 2, render it to the user

A hexagram reading has an arc: the present hexagram, the changing lines, and the transformed hexagram as the outcome. Show the arrow.

export function HexagramReading({ reading }: { reading: any }) {
  const { hexagram, changingLinePositions, resultingHexagram } = reading;
  return (
    <article>
      <header>
        <h2>{hexagram.symbol} {hexagram.english}</h2>
        <p>{hexagram.chinese} ({hexagram.pinyin}) · {hexagram.upperTrigram} over {hexagram.lowerTrigram}</p>
      </header>
      <p><strong>Judgment.</strong> {hexagram.judgment}</p>
      <p><strong>Image.</strong> {hexagram.image}</p>
      <p>{hexagram.interpretation.general}</p>

      {changingLinePositions?.length > 0 && resultingHexagram && (
        <aside>
          <p>Changing lines at positions {changingLinePositions.join(', ')}.</p>
          <h3>Transforms into {resultingHexagram.symbol} {resultingHexagram.english}</h3>
          <p>{resultingHexagram.interpretation.general}</p>
        </aside>
      )}
    </article>
  );
}

Step 3, 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.

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.