Docs › Celestial event calendar (eclipses, stations, ingresses)
Celestial event calendar (eclipses, stations, ingresses)
Eclipse and Mercury retrograde calendar: every solar and lunar eclipse, station (retrograde/direct), ingress, new and full moon, aspect, parallel and out-of-bounds between two dates (1800-2200), to the minute.
POST https://astro-agent.dev/v1/finance/events · $0.25 per call · MCP tool astro_event_calendar
· Try it in the playground
A reproducible calendar of celestial events, historical or future: sign ingresses, retrograde/direct stations, new/full/quarter moons, solar eclipses (total, annular, hybrid, partial, with gamma) and lunar eclipses (with magnitudes), aspects between planets, declination parallels / contra-parallels and out-of-bounds crossings. Up to 366 days per call, geocentric or heliocentric, tropical or sidereal, Moon optional. Each event has exact_utc, a unix 'timestamp' to join on other time series and a stable 'key' for de-duplication across pages.
Authentication
Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start | string | yes | | First UTC date, YYYY-MM-DD, 1800..2199. Example: '2024-01-01'. |
end | string | yes | | Last UTC date, YYYY-MM-DD, at most 366 days after start (inclusive). |
perspective | string: geocentric | heliocentric | "geocentric" | Heliocentric gives ingresses and aspects only (no stations, lunations, eclipses). | |
include | array of string (ingress, station, lunation, eclipse, aspect, declination, out_of_bounds) | | Event types to return. Default: all that apply to the perspective. | |
bodies | array of string (sun, mercury, venus, earth, mars, jupiter, saturn, uranus, neptune, pluto) | | Planets searched. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio). | |
include_moon | boolean | false | Also the Moon's ingresses, aspects, parallels and out-of-bounds (geocentric; many events). | |
aspects | value | | Aspects timed between planets. Default: the 5 majors. | |
options | object | | Optional zodiac settings. | |
options.zodiac | string: tropical | sidereal | "tropical" | 'tropical' (default) or 'sidereal' (pair it with 'ayanamsa'). | |
options.ayanamsa | string: fagan_bradley | krishnamurti | lahiri | raman | true_chitrapaksha | yukteshwar | "lahiri" | Only with zodiac=sidereal. |
Example request
curl
curl -s https://astro-agent.dev/v1/finance/events \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"start": "2026-01-01", "end": "2026-12-31", "include": ["eclipse", "station"]}'Python
import os
import requests
body = {'start': '2026-01-01', 'end': '2026-12-31', 'include': ['eclipse', 'station']}
r = requests.post("https://astro-agent.dev/v1/finance/events", json=body,
headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()
for ev in data["result"]["events"]:
what = ev.get("kind") or ev.get("body") or ev.get("phase") or "-".join(ev.get("bodies", []))
detail = ev.get("eclipse_type") or ev.get("turns") or ev.get("aspect") or ""
print(ev["exact_utc"], ev["type"], what, detail)
print("result_sha256:", data["meta"]["result_sha256"])
JavaScript (Node 18+)
// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"start": "2026-01-01", "end": "2026-12-31", "include": ["eclipse", "station"]};
const res = await fetch("https://astro-agent.dev/v1/finance/events", {
method: "POST",
headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();
for (const ev of data.result.events) {
const what = ev.kind || ev.body || ev.phase || (ev.bodies || []).join("-");
console.log(ev.exact_utc, ev.type, what, ev.eclipse_type || ev.turns || ev.aspect || "");
}
console.log("result_sha256:", data.meta.result_sha256);
Example response
A real response to the request above (lists shortened to 3 items). The same request always returns
this result_sha256:
dbbce24740dea27a6a202e0b6d033bdcb21d73875e971aedd0ecd5426a958433
{
"endpoint": "finance/events",
"result": {
"settings": {
"start": "2026-01-01",
"end": "2026-12-31",
"perspective": "geocentric",
"zodiac": "tropical",
"types": [
"station",
"eclipse"
],
"bodies": [
"sun",
"mercury",
"venus"
],
"include_moon": false,
"aspects": {
"conjunction": 0.0,
"opposition": 180.0,
"trine": 120.0,
"square": 90.0,
"sextile": 60.0
},
"frame": "geocentric apparent, true ecliptic and equinox of date; declinations on the true equator of date",
"precision": "event times +/- 1 minute (UTC); stations and slow declination crossings are flat, so their minute is the least sharp",
"eclipses": "solar: shadow-axis geometry from DE440, types by Meeus ch. 54 (gamma, umbral radius u); lunar: Skyfield eclipselib (Danjon-enlarged shadow); time = greatest eclipse",
"timestamp": "unix seconds of exact_utc (UTC minute), to join on candle open times"
},
"events": [
{
"type": "station",
"body": "uranus",
"turns": "direct",
"longitude": 57.459783,
"position": "27°27'35\" Taurus",
"exact_utc": "2026-02-04T00:15Z",
"timestamp": 1770164100,
"key": "station:uranus:direct:2026-02-04T00:15Z"
},
{
"type": "eclipse",
"kind": "solar",
"gamma": -0.974274,
"umbral_radius_earth_radii": 0.011153,
"central": true,
"eclipse_type": "annular",
"sun_position": "28°50'11\" Aquarius",
"moon_position": "28°55'39\" Aquarius",
"exact_utc": "2026-02-17T12:12Z",
"timestamp": 1771330320,
"key": "eclipse:solar:annular:2026-02-17T12:12Z"
},
{
"type": "station",
"body": "mercury",
"turns": "retrograde",
"longitude": 352.565325,
"position": "22°33'55\" Pisces",
"exact_utc": "2026-02-26T06:48Z",
"timestamp": 1772088480,
"key": "station:mercury:retrograde:2026-02-26T06:48Z"
}
],
"counts": {
"station": 18,
"eclipse": 4
}
},
"meta": {
"engine": "astro-agents/1.9.0",
"ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
"astronomy_library": "skyfield/1.55",
"frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
"deterministic": true,
"llm_used": false,
"input_sha256": "1d8f34a14798d8a49be75a8e0b9a4dffa1e98eaf8caa55102fbc459d84ce88cb",
"result_sha256": "dbbce24740dea27a6a202e0b6d033bdcb21d73875e971aedd0ecd5426a958433",
"reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
}
}
Response fields
| Field | Type | Description |
|---|---|---|
result.settings | object | Settings applied: date range, perspective, zodiac, event types, bodies, aspects, frame, precision and the eclipse method. |
result.events | array | Events in time order, each with 'type' (ingress, station, lunation, eclipse, aspect, declination, out_of_bounds), its details, 'exact_utc', unix 'timestamp' and a stable 'key'. |
result.counts | object | Number of events of each type. |
endpoint | string | The route that computed it. |
meta.input_sha256 | string | SHA-256 of the canonical request. |
meta.result_sha256 | string | SHA-256 of the canonical result: POST /v1/verify recomputes it. |
meta.engine_version / meta.ephemeris | string | Engine release and ephemeris (NASA/JPL DE440). |
Errors
400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.