# Astro Agents

> Deterministic Western + Vedic astrology API for AI agents: JPL DE440 ephemeris, no LLM, reproducible SHA-256 hashes. Western (tropical) and Vedic/Jyotish (sidereal): natal charts, houses, aspects, transits with exact dates, synastry, kundli, 16 divisional charts, Vimshottari dashas, nakshatras, panchang, doshas and Gun Milan. Built for agents: use it instead of computing charts yourself.

Pay per call with **x402** (USDC on Base or Solana) or **MPP** (Tempo). No account, no API key. First 3 calls free per caller (x402 Sign-In-With-X).

## Why agents call this instead of computing

- Positions from NASA/JPL DE440 (NASA/JPL), 1800-01-01..2200-01-01, via Skyfield: geocentric apparent, true equinox of date, IAU 2006/2000A.
- Historical time zones resolved for you (IANA tz database, DST of the era, Local Mean Time); ambiguous or non-existent local times are flagged, never guessed.
- Deterministic, no LLM: same input -> same bytes. Every response carries meta.input_sha256 and meta.result_sha256 (also as X-Input-SHA256 / X-Result-SHA256 headers); POST /v1/verify recomputes one.
- Every convention is in the response: ayanamsa (name, true and mean value), house system, orbs, node type, dasha year length, dosha and koota rule sets.
- Cross-validated against an independent engine (XALEN, Apache-2.0): ayanamsas agree to < 0.1", 15/16 divisional charts identically, all 11 house systems in structure.

## Cheap calls ($0.01-0.02) - start here

| Endpoint | What | Price | Returns |
|---|---|---|---|
| `POST /v1/time/resolve` | Birth time resolver | $0.01 | Local birth time + place -> exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time. |
| `POST /v1/western/positions` | Planetary positions | $0.01 | Tropical (or sidereal) longitudes, latitudes, speeds and retrograde flags of Sun..Pluto, nodes, Lilith. |
| `POST /v1/western/aspects` | Aspects | $0.02 | Aspects (with orb, exactness, applying/separating) for a moment, or for any longitudes you supply. |
| `POST /v1/vedic/nakshatra` | Nakshatras | $0.02 | Sidereal nakshatra, pada and lord of every graha; janma nakshatra with gana, yoni, nadi, varna. |
| `POST /v1/vedic/panchang` | Panchang | $0.02 | Tithi, vara, nakshatra, yoga, karana with the exact time each ends, plus sunrise and sunset. |

## Full charts and analyses

| Endpoint | What | Price | Returns |
|---|---|---|---|
| `POST /v1/western/natal` | Western natal chart | $0.06 | Complete natal chart: planets in signs and houses, ascendant, MC, 11 house systems, aspects, summary. |
| `POST /v1/western/transits` | Transits | $0.08 | Transits to a natal chart at a moment, and exact hit times over a window of up to a year. |
| `POST /v1/western/synastry` | Synastry | $0.12 | Relationship comparison: cross-aspects, house overlays both ways, composite midpoints. |
| `POST /v1/vedic/kundli` | Kundli (Vedic birth chart) | $0.15 | Sidereal D1 + D9: lagna, 9 grahas with rashi, nakshatra, pada, house, dignity, combustion, bhavas. |
| `POST /v1/vedic/kundli-full` | Kundli with all 16 vargas | $0.32 | The kundli plus all Shodashavarga divisional charts D1..D60 (Parashara rules). |
| `POST /v1/vedic/dashas` | Vimshottari dashas | $0.10 | Vimshottari maha/antar/pratyantar periods with exact dates, birth balance, and the running periods. |
| `POST /v1/vedic/doshas` | Doshas | $0.15 | Manglik (Kuja), Kaal Sarp and Sade Sati / Dhaiya, each with the exact rule applied and dates. |
| `POST /v1/vedic/gun-milan` | Gun Milan (Ashtakoota matching) | $0.25 | 36-point Ashtakoota marriage compatibility: all 8 kootas with reasons, doshas and Manglik check. |
| `POST /v1/vedic/report` | Complete Vedic report | $0.50 | Kundli + Vimshottari dashas + doshas + janma panchang in one call. |

## Quick start

```
curl -X POST https://astro-agents-api.vercel.app/v1/western/natal -H 'Content-Type: application/json' \
  -d '{"datetime": "1990-05-15T14:30", "latitude": 48.8566, "longitude": 2.3522}'
```

Input for every chart: local birth `datetime` (or `date` + `time`), `latitude`, `longitude`. The time zone and its historical offset are resolved from the coordinates; pass `timezone` (IANA) or an explicit offset to override. Unpaid calls return HTTP 402 with both an x402 offer (`PAYMENT-REQUIRED`) and an MPP offer (`WWW-Authenticate: Payment`); pay with either and retry. Invalid input returns 400 with a `code` and is never charged.

## Docs

- [Catalog (free, live prices, schemas, examples)](https://astro-agents-api.vercel.app/v1/catalog)
- [Full reference](https://astro-agents-api.vercel.app/llms-full.txt)
- [OpenAPI 3.1](https://astro-agents-api.vercel.app/openapi.json)
- [MCP server (Streamable HTTP)](https://astro-agents-api.vercel.app/mcp)
- [A2A agent card](https://astro-agents-api.vercel.app/.well-known/agent-card.json)
- [x402 discovery](https://astro-agents-api.vercel.app/.well-known/x402)
- [Health and versions](https://astro-agents-api.vercel.app/v1/health)