# 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](/pricing).
2. Nothing else. No birth data, no account sync.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

## 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
```bash
curl "https://roxyapi.com/api/v2/iching/cast?seed=user-42" \
  -H "X-API-Key: $ROXY_API_KEY"
```

### TypeScript SDK
```typescript
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);
```

### Python SDK
```python
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 SDK
```php
<?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);
```

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

Then ask Claude, "cast an I Ching reading for me." The agent calls the cast tool and explains the hexagram plus any changing lines. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

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`](/docs/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.

```tsx
'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`](/api-reference#tag/i-ching/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`](/api-reference#tag/i-ching/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`](/api-reference#tag/i-ching/GET/iching/hexagrams) returns the full list (cache once, browse offline). [`GET /iching/hexagrams/{number}`](/api-reference#tag/i-ching/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.

```bash
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](/api-reference#tag/i-ching).

## Ready-made starter

The [/starters/astrology-ai-chatbot](/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](/docs/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](/docs/tutorials/ai-chatbot) 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](/docs/tutorials/horoscope-widget) to call `/iching/daily` instead. Typed calls live in the [SDK guide](/docs/sdk).