About I Ching Explorer

Enter your question in the text field at the top of the Explorer page, then choose your method and style.

Throwing method:

• Three Coins — the modern standard; each line has equal 1/8 chance of being moving
• Yarrow Stalks — the traditional method; yin and yang moving lines have different probabilities, reflecting the original practice

Throwing style:

• Line by Line — throw each of the six lines one at a time for a more ceremonial experience
• Quick Throw — generate all six lines automatically

Press Cast Reading to begin. Free accounts can cast 1 reading per day; premium accounts get 10.

After casting, a detail view opens showing your present Hexagram with its Judgement, Image, and any moving line texts. Click on any section heading to expand the full interpretation.

If your reading has moving lines, a second "future" Hexagram is shown — formed by flipping each moving line to its opposite.

Click hexagram symbols within a reading to explore those Hexagrams in detail.

Every reading you cast is saved automatically and appears in the Reading History grid below the casting area. Click any card to reopen its full detail view. History is paginated and can be collapsed out of view by clicking on the "Reading History" header.

The Hexagram grid shows all 64 Hexagrams with their number, symbol, and name. Below it, the Trigram grid shows all 8 Trigrams. Click any cell to open a detail view with the name, structure, Judgement, Image, and line texts.

From a Hexagram detail view you can click its upper or lower trigram to navigate deeper, and use the back button to return.

The source selector (in your Profile settings) lets you switch between different I Ching translations. System sources like Wilhelm are built-in and available to everyone.

You can also create your own source via + Add New Source, then edit translations directly from any Hexagram or Trigram detail view. Your custom sources are private to your account.

After registering, verify your email to unlock casting. Your Profile page (accessible from the Explorer header) has three tabs:

• Settings — choose a translation source, as well as default throwing method and throwing style
• Security — change your password
• Subscription — view your plan, daily reading usage, and upgrade or manage billing

Premium subscribers can generate API keys to interact with I Ching Explorer programmatically. Keys are managed from the Security tab on your Profile page.

Creating a key:

• Give your key a label (e.g. "My script" or "CI pipeline") and click Generate
• The full key is shown once — copy it immediately and store it securely. It cannot be retrieved later.

Authentication: include your key in the Authorization header:

Authorization: Bearer ich_live_your_key_here

Endpoints:

• POST /api/readings/cast — cast a reading server-side. Send question, method (yarrow or coin), and optionally intentions.
• POST /api/readings — submit a manually thrown reading with your own lineValues, presentHexagram, and futureHexagram.
• GET /api/readings — list your readings. Supports filters: since, before, method, style, hexagram, futureHexagram, question, limit, offset.
• GET /api/readings/quota — check your remaining daily readings.
• GET /api/hexagram/:number — get a hexagram translation. Add ?source=name to choose a translation source.
• GET /api/hexagram/bulk/:numbers — get multiple hexagram translations in one call. Pass comma-separated numbers (e.g. /bulk/1,2,42).
• GET /api/trigram/:number — get a trigram translation (1–8). Add ?source=name to choose a source.
• GET /api/trigram/bulk/:numbers — get multiple trigram translations (e.g. /bulk/1,5).

Response objects:

Reading endpoints (POST /cast, POST /, GET /:id) return a single reading object. GET /api/readings returns an array of the same, sorted newest first.

{
  "id":              "string  — unique reading ID",
  "question":        "string",
  "intentions":      "string",
  "method":          "yarrow | coin | manual",
  "style":           "user | daily | weekly | monthly | annual",
  "presentHexagram": 1–64,
  "futureHexagram":  1–64,
  "movingLines":     [1–6, ...]  — line positions that are moving (empty if none),
  "lineValues":      [6|7|8|9, ...]  — one value per line, bottom (index 0) to top,
  "owner":           "uuid | null",
  "timestamp":       "ISO 8601 string"
}

GET /api/readings/quota returns:

{
  "allowed":   true | false,
  "remaining": 0–N,
  "limit":     1 | 10,
  "used":      0–N,
  "tier":      "free | basic"
}

Hexagram and trigram endpoints return a translation object. GET /bulk returns an object keyed by number.

{
  "hexagramNumber":         1–64,
  "name_raw":               "original text",
  "name_translation":       "translated name",
  "name_interpretation":    "interpretive note",
  "judgment_raw":           "original text",
  "judgment_translation":   "...",
  "judgment_interpretation": "...",
  "image_raw":              "original text",
  "image_translation":      "...",
  "image_interpretation":   "...",
  "line1_raw" … "line6_raw":               "line text for each moving line",
  "line1_translation" … "line6_translation": "...",
  "line1_interpretation" … "line6_interpretation": "..."
}

Trigram translations follow the same shape with trigramNumber (1–8) and no line fields.

Limits:

• Daily reading quota applies the same as in the browser (1/day free, 10/day premium)
• Write rate limit (POST): 5 req/min (free), 20/min (premium)
• Read rate limit (GET): 30 req/min (free), 60/min (premium)
• API keys can be revoked at any time from the Security tab