# Steer Astro — Vedic astrology API for AI agents

> Accurate Vedic (sidereal, Lahiri) astrology calculations as structured JSON: panchang, birth chart with divisional charts,
> Vimshottari dasha, transits, compatibility (Guna Milan), Ashtakavarga and Shadbala. You interpret; we calculate.

## Endpoints
- MCP (Streamable HTTP, stateless): https://api.steerastro.com/mcp
- REST: POST https://api.steerastro.com/v1/<tool> with a JSON body
- OpenAPI: https://api.steerastro.com/openapi.json

## Tools
- `panchang` (free): FREE. Daily Hindu panchang for any place and date: tithi, nakshatra, yoga, karana with start/end times, vara, sunrise/sunset/moonrise/moonset, lunar month (amanta/purnimanta), samvat, ritu; Rahu Kaal, Yamaganda, Gulika, Durmuhurtam, Varjyam; Abhijit, Brahma, Vijaya, Godhuli muhurtas, Amrit Kaal; with detail=full also choghadiya, hora, panchaka rahita and more.
- `birth_chart`: Vedic (sidereal, Lahiri) natal chart: ascendant, the 9 grahas with sign, whole-sign house, nakshatra/pada, dignity, retrograde/combust, functional nature; houses with lords and occupants; divisional charts (D9 by default, any of D2..D60 on request); named yogas, chara karakas, arudha lagna, planetary aspects (drishti); and doshas (Mangal/Kuja, Kaal Sarp, Pitra).
- `vimshottari_dasha`: Vimshottari dasha periods, token-efficient: returns the periods running on a date (maha → antar → pratyantar → sookshma) plus ONE level of the hierarchy at a time (9 rows). Drill down with `path`, or list a date range at one level with from/to/level.
- `transits`: Gochara (planetary transits): sidereal positions of the 9 grahas at a moment with retrograde status, upcoming sign ingresses and retrograde/direct stations (default next 365 days). With `birth`: transit houses from natal lagna and Moon, natal planets conjoined, Ashtakavarga bindus of each transit, Sade Sati phase and periods, and the Moon's Tara Bala / Chandrashtama.
- `compatibility`: Ashtakoota Guna Milan (36-point) marriage compatibility between two birth charts: all 8 kootas with scores and maxima, Nadi/Bhakoot dosha flags, both partners' Moon sign/nakshatra, and Manglik (Mangal dosha) status of each.
- `ashtakavarga`: Ashtakavarga: Bhinnashtakavarga (BAV) bindus for the 7 planets and the lagna in each sign, Sarvashtakavarga (SAV) per sign and per house from the ascendant, strongest/weakest houses; optionally the reduced (shodhita) tables. Used for transit strength.
- `shadbala`: Shadbala (six-fold planetary strength) for Sun..Saturn: Sthana, Dig, Kala, Chesta, Naisargika and Drik bala in virupas and rupas, required minimum, strength ratio and rank; Ishta/Kashta phala; and Bhava Bala for the 12 houses.

## Inputs (important)
- Look up the place's latitude/longitude and IANA time zone yourself first (e.g. Jaipur: lat 26.9124, lon 75.7873, tz "Asia/Kolkata").
- Birth `datetime` is LOCAL wall-clock time at the birthplace, e.g. "1990-03-12T15:15". Do not convert to UTC: the API applies the
  historically correct offset (war time, DST history). Every response echoes `resolved` (utc, offset, tz) — show it to the user if unsure.
- Unknown birth time: pass T12:00 and `time_unknown: true` (ascendant/houses are omitted).

## Pricing and payment (no signup, no API key)
- `panchang` is free (rate limited per IP).
- Every other tool needs a week pass for 7 days (60 requests per minute): $2.00 by card/Link, or $1.00 in USDC (MPP or x402).
- Call a paid tool (or POST https://api.steerastro.com/v1/pass) without a pass → HTTP 402 with the offer and payment options
  (MPP: `WWW-Authenticate: Payment`; x402: `PAYMENT-REQUIRED`). Pay with your agent wallet, retry the same request.
- The paid response contains `pass.token`; send `Authorization: Bearer <token>` (MCP: `pass` argument) for the rest of the week.
- Lost it? POST https://api.steerastro.com/v1/pass/recover {"payment_reference": "<payment id or tx hash>"}.

## Example
curl -s https://api.steerastro.com/v1/panchang -H 'content-type: application/json' \
  -d '{"lat":26.9124,"lon":75.7873,"tz":"Asia/Kolkata","date":"2026-10-20"}'

curl -s https://api.steerastro.com/v1/birth_chart -H 'content-type: application/json' -H 'authorization: Bearer <pass>' \
  -d '{"birth":{"datetime":"1990-03-12T15:15","lat":26.9124,"lon":75.7873,"tz":"Asia/Kolkata","place":"Jaipur"}}'

## Dasha without flooding your context
`vimshottari_dasha` returns the running chain (maha → antar → pratyantar → sookshma) and ONE level (9 rows). Drill down with
`path`: [] → mahadashas, ["Jupiter"] → its antardashas, ["Jupiter","Saturn"] → pratyantardashas. Or list a date range at one level
with `from`/`to`/`level`.

## Privacy
Stateless: birth data is used only to compute the response; it is not stored or logged.