I Ching Hexagram API

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

Request

GET /api/v2/iching/hexagrams/lookup

Response

Structured JSON with documented fields, verified against NASA JPL Horizons across 828 gold-standard tests. Not hallucinated text.

{
  "number": 1,
  "symbol": "䷀",
  "chinese": "乾",
  "english": "The Creative",
  "pinyin": "Qián",
  "binary": "111111",
  "upperTrigram": "Heaven",
  "lowerTrigram": "Heaven",
  "judgment": "Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.",
  "image": "Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.",
  "interpretation": {
    "general": "This hexagram represents the primal power of creation and the energy of pure initiative.",
    "love": "A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.",
    "career": "Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.",
    "decision": "The time is right for bold action. Trust your instincts and move forward with confidence.",
    "advice": "Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort."
  },
  "changingLines": [
    {
      "position": 1,
      "text": "The dragon is still hidden below the surface, so it does not act."
    }
  ]
}

Supported options

Call it in your language in seconds.

Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.iching.lookupHexagram({ query: { lines: '111111' } })

from roxy_sdk import create_roxy

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

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->iching->lookupHexagram(lines: '111111');

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Iching.Hexagrams.Lookup.GetAsync();

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

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Iching.LookupHexagram(ctx, nil)

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

More I Ching Hexagram endpoints

The I Ching Hexagram API bundles these related endpoints under one key.

Remote MCP for AI agents

Every I-Ching endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.

claude mcp add --transport http \
  roxy-iching https://roxyapi.com/mcp/iching \
  --header "X-API-Key: YOUR_KEY"

Tool name for GET /iching/hexagrams/lookup: get_iching_hexagrams_lookup. Full MCP setup guide

What you can build

Drop-in UI components

Render I Ching Hexagram API responses without building charts yourself. These open source, framework-agnostic web components take the typed response and draw it, in React, Vue, Svelte, Angular, plain HTML, and WordPress.

Related capabilities

I Ching Hexagram API FAQ