# I-Ching Oracle API

> I-Ching oracle API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Access 3,000 years of Chinese wisdom with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career, and decision-making. Cast readings with the authentic three-coin method, get daily hexagrams, and explore the Book of Changes programmatically. 9+ endpoints optimized for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products.

Bring 3,000 years of I-Ching wisdom to your app. In days.

- Product page: https://roxyapi.com/products/iching-api
- OpenAPI spec: https://roxyapi.com/api/v2/iching/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/iching
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <50ms
- uptime: 99.9%
- endpoints: 9+

## Features

- Complete 64 hexagram database with King Wen sequence, traditional Chinese names, pinyin, Unicode symbols, and binary patterns for authentic I-Ching readings
- Modern interpretations for each hexagram covering general meaning, love and relationships, career guidance, decision-making wisdom, and actionable advice
- 384 changing line interpretations (6 lines x 64 hexagrams) explaining how each line transforms your reading and what the transition means for your situation
- Authentic three-coin casting method with changing lines, resulting hexagram transformation, and seeded reproducibility for personalized daily oracle readings
- Daily hexagram and daily cast endpoints with date-based seeding for consistent daily wisdom features, oracle of the day, and contemplation prompts
- AI-optimized JSON responses with structured hexagram data, trigram analysis, and interpretations, perfect for MCP-powered I-Ching chatbots and LLM integration
- Multi-language responses in 8 languages (EN, TR, DE, ES, HI, PT, FR, RU) via ?lang= query parameter

## Use Cases

- Build I-Ching divination apps with authentic coin-toss readings: users ask their question and receive complete hexagram interpretations with changing lines and transformations
- Add daily oracle features to wellness and meditation apps: daily hexagrams, daily cast readings, and contemplation prompts from 3,000 years of Chinese philosophy
- Build AI I-Ching chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers oracle endpoints and delivers conversational hexagram readings
- Create Chinese philosophy education platforms teaching the Book of Changes, Taoist principles, trigram symbolism, and hexagram patterns through interactive exploration
- Ship comprehensive spiritual guidance platforms combining I-Ching with astrology, tarot, numerology, and dream interpretation under one API key
- Power decision-making and journaling apps: users record situations, cast hexagrams, track how readings relate to outcomes, and gain clarity through structured ancient wisdom

## Languages

en, de, es, fr, hi, pt, ru, tr

## Endpoints

- `POST /api/v2/iching/daily` Get daily I-Ching hexagram
- `POST /api/v2/iching/daily/cast` Cast daily I-Ching reading with changing lines
- `GET /api/v2/iching/hexagrams` List all 64 hexagrams
- `GET /api/v2/iching/hexagrams/random` Get a random hexagram
- `GET /api/v2/iching/hexagrams/lookup` Lookup hexagram by line pattern
- `GET /api/v2/iching/hexagrams/{number}` Get hexagram by number
- `GET /api/v2/iching/cast` Cast an I-Ching reading
- `GET /api/v2/iching/trigrams` List all 8 trigrams
- `GET /api/v2/iching/trigrams/{id}` Get trigram by number or name

## Example Response

```
GET /api/v2/iching/cast
```

```json
{
  "hexagram": {
    "number": 11,
    "symbol": "䷊",
    "chinese": "泰",
    "english": "Peace",
    "pinyin": "Tai",
    "upperTrigram": "Earth",
    "lowerTrigram": "Heaven",
    "judgment": "Peace. The small departs, the great approaches. Good fortune. Success.",
    "image": "Heaven and earth unite: the image of Peace. The ruler fashions the way of heaven and earth.",
    "interpretation": {
      "general": "A period of harmony and prosperity. Heaven and earth are in balance...",
      "love": "Deep mutual understanding and emotional harmony flourish now...",
      "career": "Exceptional opportunities for advancement and collaboration...",
      "decision": "The time is right for bold action. Conditions strongly favor your plans...",
      "advice": "Embrace this harmonious period. Build partnerships and share abundance..."
    }
  },
  "lines": [
    7,
    8,
    9,
    7,
    6,
    8
  ],
  "changingLinePositions": [
    3,
    5
  ],
  "resultingHexagram": {
    "number": 34,
    "english": "The Power of the Great",
    "symbol": "䷡"
  }
}
```

## Quick Start

```bash
curl -H "X-API-Key: ${ROXY_API_KEY}" -H "Content-Type: application/json" \
  https://roxyapi.com/api/v2/iching/...
```

For full request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/iching/openapi.json.